From 9add51bc6dcf95901fdbf6acfb390476417556d0 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Wed, 19 Sep 2018 16:10:46 +1000
Subject: [PATCH] doc: Re-add summaries of what children each menu item has

Slightly different to the original version of this, but same goal.
---
 components/mqtt/Kconfig              |  2 +-
 tools/kconfig_new/gen_kconfig_doc.py | 61 ++++++++++++++++++++--------
 2 files changed, 46 insertions(+), 17 deletions(-)

diff --git a/components/mqtt/Kconfig b/components/mqtt/Kconfig
index 323cc3990..624b28673 100644
--- a/components/mqtt/Kconfig
+++ b/components/mqtt/Kconfig
@@ -84,7 +84,7 @@ config MQTT_TASK_CORE_SELECTION_ENABLED
     help
         This will enable core selection
 
-choice
+choice MQTT_TASK_CORE_SELECTION
     depends on MQTT_TASK_CORE_SELECTION_ENABLED
     prompt "Core to use ?"
     config MQTT_USE_CORE_0
diff --git a/tools/kconfig_new/gen_kconfig_doc.py b/tools/kconfig_new/gen_kconfig_doc.py
index e5e6968f1..7cbc99e90 100644
--- a/tools/kconfig_new/gen_kconfig_doc.py
+++ b/tools/kconfig_new/gen_kconfig_doc.py
@@ -21,6 +21,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 import os
+import re
 import kconfiglib
 
 # Indentation to be used in the generated file
@@ -40,6 +41,11 @@ def write_docs(config, filename):
     with open(filename, "w") as f:
         config.walk_menu(lambda node: write_menu_item(f, node))
 
+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 get_breadcrumbs(node):
     # this is a bit wasteful as it recalculates each time, but still...
@@ -51,6 +57,16 @@ def get_breadcrumbs(node):
         node = node.parent
     return " > ".join(result)
 
+def get_link_anchor(node):
+    try:
+        return "CONFIG_%s" % node.item.name
+    except AttributeError:
+        assert(node_is_menu(node))  # only menus should have no item.name
+
+    result = "%s-%s" % (get_breadcrumbs(node), node.prompt[0])
+    result = re.sub(r"[^a-zA-z0-9]+", "-", result).lower()
+    return result
+
 def get_heading_level(node):
     # bit wasteful also
     result = INITIAL_HEADING_LEVEL
@@ -71,38 +87,37 @@ def format_rest_text(text, indent):
     text += '\n'
     return text
 
-def write_menu_item(f, node):
+def node_should_write(node):
     if not node.prompt:
-        return  # Don't do anything for invisible menu items
+        return False  # Don't do anything for invisible menu items
 
     if isinstance(node.parent.item, kconfiglib.Choice):
-        return  # Skip choice nodes, they are handled as part of the parent (see below)
+        return False  # Skip choice nodes, they are handled as part of the parent (see below)
+
+    return True
+
+def write_menu_item(f, node):
+    if not node_should_write(node):
+        return
 
     try:
         name = node.item.name
     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:
+        # if no symbol name, use the prompt as the heading
         title = node.prompt[0]
 
-    # if no symbol name, use the prompt as the heading
-    if True or is_menu:
-        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)
+    f.write(".. _%s:\n\n" % get_link_anchor(node))
+    f.write('%s\n' % title)
+    f.write(HEADING_SYMBOLS[get_heading_level(node)] * len(title))
+    f.write('\n\n')
 
     if name:
         f.write('%s%s\n\n' % (INDENT, node.prompt[0]))
@@ -131,6 +146,20 @@ def write_menu_item(f, node):
 
         f.write('\n\n')
 
+    if is_menu:
+        # enumerate links to child items
+        first = True
+        child = node.list
+        while child:
+            try:
+                if node_should_write(child):
+                    if first:
+                        first = False
+                    f.write('- :ref:`%s`\n' % get_link_anchor(child))
+            except AttributeError:
+                pass
+            child = child.next
+        f.write('\n')
 
 if __name__ == '__main__':
     print("Run this via 'confgen.py --output doc FILENAME'")