genrest: Show symbol help texts on index page

Instead of showing the prompt for symbols on the index page, show their
help texts. This makes searching easier.

Fall back on the prompt if no help text is available.

Also change the code to only show one of the prompts if several are
available (happens if a symbol is defined in multiple locations and adds
a prompt in more than one of them). It's probably overkill to show them
all, and it doesn't come up that often.

Suggested by David B. Kinder.

Co-authored-by: David B. Kinder <[email protected]>
Signed-off-by: Ulf Magnusson <[email protected]>

Author: 2 people

doc/scripts/genrest.py

@@ -281,21 +281,38 @@ def sym_table_rst(title, syms):
 
 .. list-table::
    :header-rows: 1
+   :widths: auto
 
    * - Symbol name
-     - Prompt
+     - Help/prompt
 """.format(title, len(title)*"*")
 
     for sym in sorted(syms, key=attrgetter("name")):
         rst += """\
    * - :option:`CONFIG_{}`
      - {}
-""".format(sym.name,
-           " / ".join(node.prompt[0] for node in sym.nodes if node.prompt))
+""".format(sym.name, sym_index_desc(sym))
 
     return rst
 
 
+def sym_index_desc(sym):
+    # Returns the description used for 'sym' on the index page
+
+    # Use the first help text, if available
+    for node in sym.nodes:
+        if node.help is not None:
+            return node.help.replace("\n", "\n       ")
+
+    # If there's no help, use the first prompt string
+    for node in sym.nodes:
+        if node.prompt:
+            return node.prompt[0]
+
+    # No help text or prompt
+    return ""
+
+
 def index_header(title, link, desc_path):
     # Returns the RST for the beginning of a symbol index page.
     #