michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: genrest: Use Kconfiglib 2 and improve output

Browse source 
The new version of the reference page for a symbol lists the following
essential and generally useful information at the top of the page:

 - Prompt

 - Type

 - Help text

 - Direct dependencies (from 'depends on', and inherited from if's and
   menus)

 - Defaults

 - Other symbols selecting or implying the symbol

The current symbol value and visibility are no longer displayed. They
don't make much sense in a reference document, as they depend on user
values from configuration files.

The bottom of the reference page also includes the symbol represented in
Kconfig format (including propagated dependencies).

All references to defined symbols appearing in expressions are turned
into links, which can be clicked on to jump to the reference page for
that symbol.

The following (slightly outdated) screenshot gives an idea of the
format:
https://www.dropbox.com/s/a34tlk2ncyus8po/promptandtype.png?dl=0

This commit also removes Kconfiglib 1, since it is no longer used.

Fixes #5622
Fixes #6821

Signed-off-by: Ulf Magnusson <ulfalizer@gmail.com>
This commit is contained in:
Ulf Magnusson 2018-03-28 18:15:01 +02:00 • committed by Anas Nashif
commit 4703ba7d31
3 changed files with 170 additions and 3723 deletions
Download patch file Download diff file Expand all files Collapse all files

4
doc/Makefile
View file

@ -73,7 +73,9 @@ content: scripts/extract_content.py
$(Q)$<
kconfig: scripts/genrest/genrest.py
$(Q)srctree=../ ENV_VAR_BOARD_DIR=boards/*/*/ ENV_VAR_ARCH=* KERNELVERSION=1.9.99 SRCARCH=x86 python3 $< ../Kconfig reference/kconfig/
$(Q)PYTHONPATH="${ZEPHYR_BASE}/scripts/kconfig:${PYTHONPATH}" \
srctree=../ ENV_VAR_BOARD_DIR=boards/*/*/ ENV_VAR_ARCH=* KERNELVERSION=1.9.99 SRCARCH=x86 \
python3 $< ../Kconfig reference/kconfig/
prep: doxy content kconfig

237
doc/scripts/genrest/genrest.py
View file

@ -1,74 +1,38 @@
# Prints a tree of all items in the configuration
# vim: tabstop=4 shiftwidth=4 expandtab
# Generates a Kconfig symbol reference in RST format, with a separate
# CONFIG_FOO.rst file for each symbol, and an alphabetical index with links in
# index.rst.
import kconfiglib
import os
import sys
import textwrap
# Integers representing symbol types
UNKNOWN, BOOL, TRISTATE, STRING, HEX, INT = range(6)
# "Extend" the standard kconfiglib.expr_str() to turn references to defined
# Kconfig symbols into RST links. Symbol.__str__() will then use the extended
# version.
#
# This is a bit hacky, but better than reimplementing Symbol.__str__() and/or
# kconfiglib.expr_str().
# Strings to use for types
TYPENAME = {UNKNOWN: "unknown", BOOL: "bool", TRISTATE: "tristate",
STRING: "string", HEX: "hex", INT: "int"}
def expr_str_rst(expr):
# Skip constant and undefined symbols by checking if expr.nodes is empty
if isinstance(expr, kconfiglib.Symbol) and expr.nodes:
# The "\ " avoids RST issues for !CONFIG_FOO -- see
# http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#character-level-inline-markup
return r"\ :option:`{0} <CONFIG_{0}>`".format(expr.name)
done = []
itemIndex = {}
# We'll end up back in expr_str_rst() when expr_str_orig() does recursive
# calls for subexpressions
return expr_str_orig(expr)
def print_with_indent(s, indent):
print((" " * indent) + s)
def print_items(items, outdir, indent):
for item in items:
if item.is_symbol() or item.is_choice():
text = item.get_help()
elif item.is_menu():
text = item.get_title()
else:
# Comment
text = item.get_text()
if item.is_symbol():
var = "CONFIG_%s" %item.get_name()
if not var in done:
done.append(var)
# Save up the config items in itemIndex, a dictionary indexed
# by the item name with the value as the "prompt" (short
# description) from the Kconfig file. (We'll output them
# later in alphabetic order
if len(item.get_prompts()) > 0:
p = item.get_prompts()[0]
else:
p = ""
itemIndex[var] = " * - :option:`%s`\n - %s\n" % (var, p)
# Create a details .rst document for each symbol discovered
config = open("%s/%s.rst" % (outdir, var), "w")
config.write(":orphan:\n\n")
config.write(".. title:: %s\n\n" %item.get_name())
config.write(".. option:: CONFIG_%s\n" %item.get_name())
config.write(".. _CONFIG_%s:\n" %item.get_name())
if text:
config.write("\n%s\n\n" %text)
else:
config.write("\nThe configuration item %s:\n\n" %var)
config.write("%s\n" %item.rest())
config.close()
elif item.is_menu():
print_items(item.get_items(), outdir, indent + 2)
elif item.is_choice():
print_items(item.get_items(), outdir, indent + 2)
elif item.is_comment():
pass
expr_str_orig = kconfiglib.expr_str
kconfiglib.expr_str = expr_str_rst
f = open("%s/index.rst" % (sys.argv[2]), "w")
f.write(""".. _configuration:
INDEX_RST_HEADER = """.. _configuration:
Configuration Options Reference Guide
#####################################
Configuration Symbol Reference
##############################
Introduction
************
@ -87,6 +51,11 @@ The configuration options' information below is extracted directly from
Click on the option name in the table below for detailed information about
each option.
For symbols defined in multiple locations, the defaults, selects, implies, and
ranges from all instances will be listed on the first instance of the symbol in
the Kconfig display on the symbol's help page. This has to do with Kconfig
internals, as those properties belong to symbols, while e.g. prompts belong to
menu entries.
Supported Options
*****************
@ -96,15 +65,143 @@ Supported Options
* - Kconfig Symbol
- Description
""")
conf = kconfiglib.Config(sys.argv[1])
print_items(conf.get_top_level_items(), sys.argv[2], 0)
"""
# print_items created separate .rst files for each configuration option as
# well as filling itemIndex with all these options (and their descriptions).
# Now we can print out the accumulated config symbols in alphabetic order.
def write_kconfig_rst():
# The "main" function. Writes index.rst and the symbol RST files.
for item in sorted(itemIndex):
f.write(itemIndex[item])
if len(sys.argv) != 3:
print("usage: {} <Kconfig> <output directory>", file=sys.stderr)
sys.exit(1)
f.close()
kconf = kconfiglib.Kconfig(sys.argv[1])
out_dir = sys.argv[2]
with open(os.path.join(out_dir, "index.rst"), "w") as index_rst:
index_rst.write(INDEX_RST_HEADER)
# - Sort the symbols by name so that they end up in sorted order in
# index.rst
#
# - Use set() to get rid of duplicates for symbols defined in multiple
# locations.
for sym in sorted(set(kconf.defined_syms), key=lambda sym: sym.name):
# Write an RST file for the symbol
write_sym_rst(sym, out_dir)
# Add an index entry for the symbol that links to its RST file.
# Also list its prompt(s), if any. (A symbol can have multiple
# prompts if it has multiple definitions.)
#
# The strip() avoids RST choking on stuff like *foo *, when people
# accidentally include leading/trailing whitespace in prompts.
index_rst.write(" * - :option:`CONFIG_{}`\n - {}\n"
.format(sym.name,
" / ".join(node.prompt[0].strip()
for node in sym.nodes
if node.prompt)))
def write_sym_rst(sym, out_dir):
# Writes documentation for 'sym' to <out_dir>/CONFIG_<sym.name>.rst
kconf = sym.kconfig
with open(os.path.join(out_dir, "CONFIG_{}.rst".format(sym.name)),
"w") as sym_rst:
# List all prompts on separate lines
prompt_str = "\n\n".join("*{}*".format(node.prompt[0].strip())
for node in sym.nodes if node.prompt) \
or "*(No prompt -- not directly user assignable.)*"
# - :orphan: suppresses warnings for the symbol RST files not being
# included in any toctree
#
# - '.. title::' sets the title of the document (e.g. <title>). This
# seems to be poorly documented at the moment.
sym_rst.write(":orphan:\n\n"
".. title:: {0}\n\n"
".. option:: CONFIG_{0}\n\n"
"{1}\n\n"
"Type: ``{2}``\n\n"
.format(sym.name,
prompt_str,
kconfiglib.TYPE_TO_STR[sym.type]))
# Symbols with multiple definitions can have multiple help texts
for node in sym.nodes:
if node.help is not None:
sym_rst.write("Help\n"
"====\n\n"
"{}\n\n"
.format(node.help))
if sym.direct_dep is not kconf.y:
sym_rst.write("Direct dependencies\n"
"===================\n\n"
"{}\n\n"
"*(Includes any dependencies from if's and menus.)*\n\n"
.format(kconfiglib.expr_str(sym.direct_dep)))
if sym.defaults:
sym_rst.write("Defaults\n"
"========\n\n")
for value, cond in sym.defaults:
default_str = kconfiglib.expr_str(value)
if cond is not kconf.y:
default_str += " if " + kconfiglib.expr_str(cond)
sym_rst.write(" - {}\n".format(default_str))
sym_rst.write("\n")
def write_select_imply_rst(expr):
# Writes a link for each selecting symbol (if 'expr' is
# sym.rev_dep) or each implying symbol (if 'expr' is
# sym.weak_rev_dep)
#
# This relies on Kconfiglib using the following format for
# select/imply expressions:
#
# (OR, (OR, (OR, <expr 1>, <expr 2>), <expr 3>), <expr 4>)
def write_select_imply_entry(select):
# 'select A if B' turns into A && B in sym.(weak_)rev_dep
sym_rst.write(" - :option:`CONFIG_{}`\n".format(
select[1].name if isinstance(select, tuple)
else select.name))
while isinstance(expr, tuple) and expr[0] == kconfiglib.OR:
write_select_imply_entry(expr[2])
expr = expr[1]
write_select_imply_entry(expr)
sym_rst.write("\n")
if sym.rev_dep is not kconf.n:
sym_rst.write("Symbols that ``select`` this symbol\n"
"===================================\n\n")
write_select_imply_rst(sym.rev_dep)
if sym.weak_rev_dep is not kconf.n:
sym_rst.write("Symbols that ``imply`` this symbol\n"
"==================================\n\n")
write_select_imply_rst(sym.weak_rev_dep)
# parsed-literal supports links in the definition
sym_rst.write("Kconfig definition\n"
"==================\n\n"
".. parsed-literal::\n\n"
"{}\n\n"
"*(Includes propagated dependencies, including from if's and menus.)*\n\n"
.format(textwrap.indent(str(sym), " "*4)))
sym_rst.write("Definition location{}\n"
"====================\n\n"
"{}".format(
"s" if len(sym.nodes) > 1 else "",
"\n".join(" - ``{}:{}``".format(node.filename, node.linenr) for
node in sym.nodes)))
if __name__ == "__main__":
write_kconfig_rst()

3652
doc/scripts/genrest/kconfiglib.py
View file

File diff suppressed because it is too large Load diff