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.
This commit is contained in:
parent
4bbb043bc5
commit
27e17fed28
|
@ -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
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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"
|
||||
|
|
|
@ -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,10 +1988,19 @@ 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")
|
||||
|
|
Loading…
Reference in New Issue