From 27e17fed283b0e039c41a05447ef1b8a867b1b7e Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Thu, 15 Sep 2022 14:31:06 +1000 Subject: 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 | 6 +++-- doc/python_api/rst/info_api_reference.rst | 2 +- doc/python_api/rst/info_overview.rst | 6 ++--- doc/python_api/sphinx_changelog_gen.py | 6 +++-- doc/python_api/sphinx_doc_gen.py | 38 +++++++++++++++++++++---------- 5 files changed, 38 insertions(+), 20 deletions(-) (limited to 'doc/python_api') diff --git a/doc/python_api/rst/change_log.rst b/doc/python_api/rst/change_log.rst index 957bf8605e3..ef289cd0762 100644 --- a/doc/python_api/rst/change_log.rst +++ b/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 diff --git a/doc/python_api/rst/info_api_reference.rst b/doc/python_api/rst/info_api_reference.rst index 70d201016f0..3deb96dbb52 100644 --- a/doc/python_api/rst/info_api_reference.rst +++ b/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 diff --git a/doc/python_api/rst/info_overview.rst b/doc/python_api/rst/info_overview.rst index 50928963f60..638420a53ae 100644 --- a/doc/python_api/rst/info_overview.rst +++ b/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 diff --git a/doc/python_api/sphinx_changelog_gen.py b/doc/python_api/sphinx_changelog_gen.py index e2bbf7c3acd..fb93c301280 100644 --- a/doc/python_api/sphinx_changelog_gen.py +++ b/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" diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py index 0887e9e74d8..7b5f13177ef 100644 --- a/doc/python_api/sphinx_doc_gen.py +++ b/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") -- cgit v1.2.3