[Bf-blender-cvs] [27e17fed283] master: PyDoc: hide overly long titles from the side-bar
Campbell Barton
noreply at git.blender.org
Thu Sep 15 06:36:01 CEST 2022
Commit: 27e17fed283b0e039c41a05447ef1b8a867b1b7e
Author: Campbell Barton
Date: Thu Sep 15 14:31:06 2022 +1000
Branches: master
https://developer.blender.org/rB27e17fed283b0e039c41a05447ef1b8a867b1b7e
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.
===================================================================
M doc/python_api/rst/change_log.rst
M doc/python_api/rst/info_api_reference.rst
M doc/python_api/rst/info_overview.rst
M doc/python_api/sphinx_changelog_gen.py
M doc/python_api/sphinx_doc_gen.py
===================================================================
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")
More information about the Bf-blender-cvs
mailing list