PyDoc: hide overly long titles from the side-bar

The side-bar included both title and description for documentation
pages including quickstart, tips & tricks .. etc.

Titles often wrapped and took up a lot of vertical space in the side-bar.

Now these pages are linked on the main page, with the side-bar
used for top-level Python modules.

doc/python_api/rst/change_log.rst

@@ -1,7 +1,9 @@
 :tocdepth: 2
 
-Blender API Change Log
-**********************
+Change Log
+**********
+
+Changes in Blender's Python API between releases.
 
 .. note, this document is auto generated by sphinx_changelog_gen.py
 

doc/python_api/rst/info_api_reference.rst

@@ -1,6 +1,6 @@
 
 *******************
-Reference API Usage
+API Reference Usage
 *******************
 
 Blender has many interlinking data types which have an auto-generated reference API which often has the information

doc/python_api/rst/info_overview.rst

@@ -1,8 +1,8 @@
 .. _info_overview:
 
-*******************
-Python API Overview
-*******************
+************
+API Overview
+************
 
 The purpose of this document is to explain how Python and Blender fit together,
 covering some of the functionality that may not be obvious from reading the API references

doc/python_api/sphinx_changelog_gen.py

@@ -349,8 +349,10 @@ def api_changelog(args):
         fw(""
            ":tocdepth: 2\n"
            "\n"
-           "Blender API Change Log\n"
-           "**********************\n"
+           "Change Log\n"
+           "**********\n"
+           "\n"
+           "Changes in Blender's Python API between releases.\n"
            "\n"
            ".. note, this document is auto generated by sphinx_changelog_gen.py\n"
            "\n"

doc/python_api/sphinx_doc_gen.py

@@ -387,24 +387,25 @@ EXAMPLE_SET_USED = set()
 # RST files directory.
 RST_DIR = os.path.abspath(os.path.join(SCRIPT_DIR, "rst"))
 
-# extra info, not api reference docs
-# stored in ./rst/info_*
+# Extra info, not api reference docs stored in `./rst/info_*`.
+# Pairs of (file, description), the title makes from the RST files are displayed before the description.
 INFO_DOCS = (
     ("info_quickstart.rst",
-     "Quickstart: New to Blender or scripting and want to get your feet wet?"),
+     "New to Blender or scripting and want to get your feet wet?"),
     ("info_overview.rst",
-     "API Overview: A more complete explanation of Python integration"),
+     "A more complete explanation of Python integration."),
     ("info_api_reference.rst",
-     "API Reference Usage: examples of how to use the API reference docs"),
+     "Examples of how to use the API reference docs."),
     ("info_best_practice.rst",
-     "Best Practice: Conventions to follow for writing good scripts"),
+     "Conventions to follow for writing good scripts."),
     ("info_tips_and_tricks.rst",
-     "Tips and Tricks: Hints to help you while writing scripts for Blender"),
+     "Hints to help you while writing scripts for Blender."),
     ("info_gotcha.rst",
-     "Gotcha's: Some of the problems you may encounter when writing scripts"),
+     "Some of the problems you may encounter when writing scripts."),
     ("info_advanced.rst",
-     "Advanced use (topics which may not be required for typical usage)"),
-    ("change_log.rst", "Change Log: List of changes since last Blender release"),
+     "Topics which may not be required for typical usage."),
+    ("change_log.rst",
+     "List of changes since last Blender release"),
 )
 # Referenced indirectly.
 INFO_DOCS_OTHER = (
@@ -412,6 +413,10 @@ INFO_DOCS_OTHER = (
     "info_advanced_blender_as_bpy.rst",
 )
 
+# Hide the actual TOC, use a separate list that links to the items.
+# This is done so a short description can be included with each link.
+USE_INFO_DOCS_FANCY_INDEX = True
+
 # only support for properties atm.
 RNA_BLACKLIST = {
     # XXX messes up PDF!, really a bug but for now just workaround.
@@ -1911,7 +1916,7 @@ except ModuleNotFoundError:
     # fw("        'collapse_navigation': True,\n")
     fw("        'sticky_navigation': False,\n")
     fw("        'navigation_depth': 1,\n")
-    # fw("        'includehidden': True,\n")
+    fw("        'includehidden': False,\n")
     # fw("        'titles_only': False\n")
     fw("    }\n\n")
 
@@ -1983,12 +1988,21 @@ def write_rst_index(basepath):
 
     if not EXCLUDE_INFO_DOCS:
         fw(".. toctree::\n")
+        if USE_INFO_DOCS_FANCY_INDEX:
+            fw("   :hidden:\n")
         fw("   :maxdepth: 1\n")
         fw("   :caption: Documentation\n\n")
         for info, info_desc in INFO_DOCS:
-            fw("   %s <%s>\n" % (info_desc, info))
+            fw("   %s\n" % info)
         fw("\n")
 
+        if USE_INFO_DOCS_FANCY_INDEX:
+            # Show a fake TOC, allowing for an extra description to be shown as well as the title.
+            fw(title_string("Documentation", "="))
+            for info, info_desc in INFO_DOCS:
+                fw("- :doc:`%s`: %s\n" % (info.removesuffix(".rst"), info_desc))
+            fw("\n")
+
     fw(".. toctree::\n")
     fw("   :maxdepth: 1\n")
     fw("   :caption: Application Modules\n\n")