From d376105e8e45fed1dce814e67fd9520470486f26 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Fri, 17 Aug 2018 16:12:28 +1000 Subject: [PATCH] doc: Update new documentation config output Make output similar to previous implementation. --- docs/en/get-started-cmake/idf-monitor.rst | 2 +- docs/en/get-started-cmake/index.rst | 2 +- tools/kconfig_new/gen_kconfig_doc.py | 72 ++++++++++++++++------- 3 files changed, 54 insertions(+), 22 deletions(-) diff --git a/docs/en/get-started-cmake/idf-monitor.rst b/docs/en/get-started-cmake/idf-monitor.rst index 76bd8b4117..b29667cdb2 100644 --- a/docs/en/get-started-cmake/idf-monitor.rst +++ b/docs/en/get-started-cmake/idf-monitor.rst @@ -67,7 +67,7 @@ By default, if an esp-idf app crashes then the panic handler prints registers an Optionally, the panic handler can be configured to run a serial "gdb stub" which can communicate with a gdb_ debugger program and allow memory to be read, variables and stack frames examined, etc. This is not as versatile as JTAG debugging, but no special hardware is required. -To enable the gdbstub, run ``idf.py menuconfig`` and set :ref:`CONFIG_ESP32_PANIC` option to ``Invoke GDBStub``. +To enable the gdbstub, run ``idf.py menuconfig`` and set :envvar:`CONFIG_ESP32_PANIC` option to ``Invoke GDBStub``. If this option is enabled and IDF Monitor sees the gdb stub has loaded, it will automatically pause serial monitoring and run GDB with the correct arguments. After GDB exits, the board will be reset via the RTS serial line (if this is connected.) diff --git a/docs/en/get-started-cmake/index.rst b/docs/en/get-started-cmake/index.rst index faa715c8c3..8b3318a40b 100644 --- a/docs/en/get-started-cmake/index.rst +++ b/docs/en/get-started-cmake/index.rst @@ -373,7 +373,7 @@ To exit the monitor use shortcut ``Ctrl+]``. e���)(Xn@�y.!��(�PW+)��Hn9a؅/9�!�t5��P�~�k��e�ea�5�jA ~zY��Y(1�,1�� e���)(Xn@�y.!Dr�zY(�jpi�|�+z5Ymvp - or monitor fails shortly after upload, your board is likely using 26MHz crystal. Most development board designs use 40MHz and the ESP-IDF uses this default value. Exit the monitor, go back to the :ref:`menuconfig `, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash ` the application again. This is found under ``idf.py menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency. + or monitor fails shortly after upload, your board is likely using 26MHz crystal. Most development board designs use 40MHz and the ESP-IDF uses this default value. Exit the monitor, go back to the :ref:`menuconfig `, change :envvar:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash ` the application again. This is found under ``idf.py menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency. .. note:: diff --git a/tools/kconfig_new/gen_kconfig_doc.py b/tools/kconfig_new/gen_kconfig_doc.py index e5e6968f18..83a91f3599 100644 --- a/tools/kconfig_new/gen_kconfig_doc.py +++ b/tools/kconfig_new/gen_kconfig_doc.py @@ -27,10 +27,10 @@ import kconfiglib INDENT = ' ' # Characters used when underlining section heading -HEADING_SYMBOLS = '#*=-^"+' +HEADING_SYMBOLS = '*=-^#' # Keep the heading level in sync with api-reference/kconfig.rst -INITIAL_HEADING_LEVEL = 3 +INITIAL_HEADING_LEVEL = 2 MAX_HEADING_LEVEL = len(HEADING_SYMBOLS)-1 def write_docs(config, filename): @@ -46,7 +46,7 @@ def get_breadcrumbs(node): result = [] node = node.parent while node.parent: - if node.prompt: + if node_is_menu(node) and node.prompt: result = [ node.prompt[0] ] + result node = node.parent return " > ".join(result) @@ -56,7 +56,10 @@ def get_heading_level(node): result = INITIAL_HEADING_LEVEL node = node.parent while node.parent: - result += 1 + # Test for 'Component config' is a hack so component config doesn't bury all + # the components under it in the hierarchy + if node_is_menu(node) and node.prompt[0] != "Component config": + result += 1 if result == MAX_HEADING_LEVEL: return MAX_HEADING_LEVEL node = node.parent @@ -71,6 +74,27 @@ def format_rest_text(text, indent): text += '\n' return text +def node_is_menu(node): + try: + return node.item == kconfiglib.MENU or node.is_menuconfig + except AttributeError: + return False # not all MenuNodes have is_menuconfig for some reason + +def should_print_preview_links(node): + """ + Return True if we should print the preview links. For each menu, + the menu with the preview links is the top menu which contains + actual configuration items. + """ + child = node.list + while child: + if not node_is_menu(child) and child.prompt: + # we have a non-menu child, so return true if we don't have + # a parent which already returned true + return node.parent is None or not should_print_preview_links(node.parent) + child = child.next + return False + def write_menu_item(f, node): if not node.prompt: return # Don't do anything for invisible menu items @@ -83,30 +107,35 @@ def write_menu_item(f, node): except AttributeError: name = None - try: - is_menu = node.item == kconfiglib.MENU or node.is_menuconfig - except AttributeError: - is_menu = False # not all MenuNodes have is_menuconfig for some reason + is_menu = node_is_menu(node) ## Heading if name: - title = name - # add link target so we can use :ref:`CONFIG_FOO` - f.write('.. _CONFIG_%s:\n\n' % name) - else: - title = node.prompt[0] + f.write('.. envvar:: CONFIG_%s\n\n' % name) - # if no symbol name, use the prompt as the heading - if True or is_menu: + # menus get a proper heading + if is_menu: + title = node.prompt[0] f.write('%s\n' % title) f.write(HEADING_SYMBOLS[get_heading_level(node)] * len(title)) f.write('\n\n') - else: - f.write('**%s**\n\n\n' % title) + if should_print_preview_links(node): + # print preview links to all items in this menu + # for the first menu which contains at least one non-menu item + # (ie per component, or per top-level KConfig.projbuild menu) + def print_previews(parent): + child = parent.list + while child: + if not node_is_menu(child): + f.write('- :envvar:`CONFIG_%s`\n' % child.item.name) + if child.list and not isinstance(child.item, kconfiglib.Choice): + print_previews(child) + child = child.next + print_previews(node) + f.write('\n\n') if name: f.write('%s%s\n\n' % (INDENT, node.prompt[0])) - f.write('%s:emphasis:`Found in: %s`\n\n' % (INDENT, get_breadcrumbs(node))) try: if node.help: @@ -117,12 +146,16 @@ def write_menu_item(f, node): except AttributeError: pass # No help + if node.parent is not None and not is_menu: + f.write('%sFound in\n%s%s\n\n' % (INDENT, INDENT * 2, + get_breadcrumbs(node))) + if isinstance(node.item, kconfiglib.Choice): f.write('%sAvailable options:\n' % INDENT) choice_node = node.list while choice_node: # Format available options as a list - f.write('%s- %-20s (%s)\n' % (INDENT * 2, choice_node.prompt[0], choice_node.item.name)) + f.write('%s- %-20s (`CONFIG_%s`)\n' % (INDENT * 2, choice_node.prompt[0], choice_node.item.name)) if choice_node.help: HELP_INDENT = INDENT * 2 fmt_help = format_rest_text(choice_node.help, ' ' + HELP_INDENT) @@ -131,7 +164,6 @@ def write_menu_item(f, node): f.write('\n\n') - if __name__ == '__main__': print("Run this via 'confgen.py --output doc FILENAME'") -- 2.40.0