Sphinx Python Documentation (#1567) - Tweaked Sphinx configuration.

- Added a new description/about text in the sidebar, including blue link buttons to GitHub and MaterialX on Mastodon (with an SVG-based embedded icon) - Applied the "monokai" syntax highlighting theme to code snippets - Added custom Jinja templates for classes and modules, in order to add a section title before the alphabetical indices on pages - Added a custom HTML template for the navigation section in the sidebar in order to limit the depth of the table of contents - Added code to remove module names from the signatures of functions, in order to make the docs more readable
AcademySoftwareFoundation · Oct 18, 2023 · e4382bb · e4382bb
1 parent e1113ea
commit e4382bb
Show file tree

Hide file tree

Showing 5 changed files with 406 additions and 12 deletions.
diff --git a/documents/_templates/autosummary/class.rst b/documents/_templates/autosummary/class.rst
@@ -0,0 +1,43 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :show-inheritance:
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block automethods %}
+   {% if methods %}
+
+   Methods
+   -------
+
+   .. automethod:: __init__
+   .. autosummary::
+   {% for item in methods %}
+      .. automethod:: ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
diff --git a/documents/_templates/autosummary/module.rst b/documents/_templates/autosummary/module.rst
@@ -0,0 +1,63 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   Alphabetical Index
+   ------------------
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Module Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}
diff --git a/documents/_templates/sphinx-navigation.html b/documents/_templates/sphinx-navigation.html
@@ -0,0 +1,12 @@
+<h3>{{ _('Navigation') }}</h3>
+{{ toctree(maxdepth=2,
+           includehidden=theme_sidebar_includehidden,
+           collapse=theme_sidebar_collapse) }}
+{% if theme_extra_nav_links %}
+<hr />
+<ul>
+    {% for text, uri in theme_extra_nav_links.items() %}
+    <li class="toctree-l1"><a href="{{ uri }}">{{ text }}</a></li>
+    {% endfor %}
+</ul>
+{% endif %}
diff --git a/documents/sphinx-conf.py.in b/documents/sphinx-conf.py.in
@@ -7,8 +7,8 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = 'MaterialX'
-copyright = '2023, MaterialX Maintainers'
-author = 'MaterialX Maintainers'
+author = '{} Authors'.format(project)
+copyright = '2023 {}'.format(author)
 release = '${MATERIALX_LIBRARY_VERSION}'
 
 
@@ -22,26 +22,160 @@ sys.path.insert(0, os.path.abspath('${MATERIALX_PYTHONPATH}'))
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
+# Format text wrapped in single backticks as Python code objects, possibly
+# linked to the respective Python API documentation paragraph
+default_role = 'py:obj'
+
 extensions = [
     'myst_parser',
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
 ]
 
-exclude_patterns = []
+# Syntax highlighting
+pygments_style = 'monokai'
+
+templates_path = ['${CMAKE_CURRENT_SOURCE_DIR}/_templates']
+
+
+# -- Autodoc Configuration ---------------------------------------------------
+
+add_module_names = False
+autodoc_default_options = {
+    'show-inheritance': True,
+}
+
+_library_version_underscores = '${MATERIALX_LIBRARY_VERSION}'.replace(".", "_")
+
+
+def strip_module_names(text):
+    """
+    Returns the given text with prefixes of known Python modules stripped, in
+    order to make the API documentation more readable.
+    """
+    if text:
+        # Check if the given text references a type named `Input`, and if so,
+        # leave the given text as-is. Otherwise, `Input` by itself could mean
+        # either `PyMaterialXCore.Input` or `PyMaterialXRenderGlsl.Input`,
+        # leading to a warning when processing the docstring:
+        # ```
+        # docstring of PyMaterialXGenShader.PyCapsule.getNodeDefInput:1:
+        # WARNING: more than one target found for cross-reference 'Input':
+        # PyMaterialXCore.Input, PyMaterialXRenderGlsl.Input
+        # ```
+        if ".Input)" in text or ".Input, " in text or text.endswith(".Input"):
+            return text
+
+        text = (
+            text
+            .replace('MaterialX_v{}::'.format(_library_version_underscores), '')
+            .replace('PyMaterialXCore.', '')
+            .replace('PyMaterialXFormat.', '')
+            .replace('PyMaterialXGenShader.', '')
+            .replace('PyMaterialXGenGlsl.', '')
+            .replace('PyMaterialXGenOsl.', '')
+            .replace('PyMaterialXGenMdl.', '')
+            .replace('PyMaterialXGenMsl.', '')
+            .replace('PyMaterialXRender.', '')
+            .replace('PyMaterialXRenderGlsl.', '')
+            .replace('PyMaterialXRenderOsl.', '')
+            .replace('PyMaterialXRenderMsl.', '')
+
+            # Special case handling for "PyMaterialXRenderGlsl.Input", which
+            # appears in `Dict[str, GlslProgram::Input]` in one case
+            .replace('GlslProgram::Input', 'PyMaterialXRenderGlsl.Input')
+
+            # Special case handling for "PyMaterialXRenderMsl.Input", which
+            # appears in `Dict[str, MslProgram::Input]` in one case
+            .replace('MslProgram::Input', 'PyMaterialXRenderMsl.Input')
+        )
+    return text
+
+
+def autodoc_process_signature(app, what, name, obj, options, signature,
+                              return_annotation):
+    """
+    Event handler for object signatures.
+
+    Emitted when autodoc has formatted a signature for an object.
+
+    Can return a new tuple `(signature, return_annotation)` to change what
+    Sphinx puts into the output.
+
+    Args:
+        app – the Sphinx application object
+        what – the type of the object to which the docstring belongs (one of
+               "module", "class", "exception", "function", "method", "attribute")
+        name – the fully qualified name of the object
+        obj – the object itself
+        options – the options given to the directive: an object with attributes
+                  inherited_members, undoc_members, show_inheritance and no-index
+                  that are true if the flag option of same name was given to
+                  the auto directive
+        signature – function signature, as a string of the form "(parameter_1,
+                    parameter_2)", or `None` if introspection didn’t succeed
+                    and signature wasn’t specified in the directive.
+        return_annotation – function return annotation as a string of the form
+                            " -> annotation", or `None` if there is no return
+                            annotation
+    """
+    signature = strip_module_names(signature)
+    return_annotation = strip_module_names(return_annotation)
+    return (signature, return_annotation)
+
+
+def setup(app):
+    app.connect('autodoc-process-signature', autodoc_process_signature)
 
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
+about = """
+<b>MaterialX</b> &ndash; An open standard for the exchange of rich material and
+look-development content across applications and renderers.
+<p>
+  <a title="MaterialX on GitHub" class="blueButton" href="https://github.com/AcademySoftwareFoundation/MaterialX">GitHub</a>
+  &nbsp;
+  <a title="MaterialX on Mastodon" class="blueButton" href="https://mastodon.social/&#64;MaterialX&#64;fosstodon.org">
+    <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
+         alt="MaterialX on Mastodon" title="MaterialX on Mastodon" viewBox="0 0 24 24"
+         width="16" height="16" style="vertical-align: text-top;">
+      <title>MaterialX on Mastodon</title>
+      <g transform="translate(-1, 0) scale(0.32, 0.32)" fill="#d2dbde">
+        <path d="M74.7135 16.6043C73.6199 8.54587 66.5351 2.19527 58.1366 0.964691C56.7196 0.756754 51.351 0 38.9148 0H38.822C26.3824 0 23.7135 0.756754 22.2966 0.964691C14.1319 2.16118 6.67571 7.86752 4.86669 16.0214C3.99657 20.0369 3.90371 24.4888 4.06535 28.5726C4.29578 34.4289 4.34049 40.275 4.877 46.1075C5.24791 49.9817 5.89495 53.8251 6.81328 57.6088C8.53288 64.5968 15.4938 70.4122 22.3138 72.7848C29.6155 75.259 37.468 75.6697 44.9919 73.971C45.8196 73.7801 46.6381 73.5586 47.4475 73.3063C49.2737 72.7302 51.4164 72.086 52.9915 70.9542C53.0131 70.9384 53.0308 70.9178 53.0433 70.8942C53.0558 70.8706 53.0628 70.8445 53.0637 70.8179V65.1661C53.0634 65.1412 53.0574 65.1167 53.0462 65.0944C53.035 65.0721 53.0189 65.0525 52.9992 65.0371C52.9794 65.0218 52.9564 65.011 52.9318 65.0056C52.9073 65.0002 52.8819 65.0003 52.8574 65.0059C48.0369 66.1472 43.0971 66.7193 38.141 66.7103C29.6118 66.7103 27.3178 62.6981 26.6609 61.0278C26.1329 59.5842 25.7976 58.0784 25.6636 56.5486C25.6622 56.5229 25.667 56.4973 25.6775 56.4738C25.688 56.4502 25.7039 56.4295 25.724 56.4132C25.7441 56.397 25.7678 56.3856 25.7931 56.3801C25.8185 56.3746 25.8448 56.3751 25.8699 56.3816C30.6101 57.5151 35.4693 58.0873 40.3455 58.086C41.5183 58.086 42.6876 58.086 43.8604 58.0553C48.7647 57.919 53.9339 57.6701 58.7591 56.7361C58.8794 56.7123 58.9998 56.6918 59.103 56.6611C66.7139 55.2124 73.9569 50.665 74.6929 39.1501C74.7204 38.6967 74.7892 34.4016 74.7892 33.9312C74.7926 32.3325 75.3085 22.5901 74.7135 16.6043ZM62.9996 45.3371H54.9966V25.9069C54.9966 21.8163 53.277 19.7302 49.7793 19.7302C45.9343 19.7302 44.0083 22.1981 44.0083 27.0727V37.7082H36.0534V27.0727C36.0534 22.1981 34.124 19.7302 30.279 19.7302C26.8019 19.7302 25.0651 21.8163 25.0617 25.9069V45.3371H17.0656V25.3172C17.0656 21.2266 18.1191 17.9769 20.2262 15.568C22.3998 13.1648 25.2509 11.9308 28.7898 11.9308C32.8859 11.9308 35.9812 13.492 38.0447 16.6111L40.036 19.9245L42.0308 16.6111C44.0943 13.492 47.1896 11.9308 51.2788 11.9308C54.8143 11.9308 57.6654 13.1648 59.8459 15.568C61.9529 17.9746 63.0065 21.2243 63.0065 25.3172L62.9996 45.3371Z"></path>
+      </g>
+    </svg>
+  </a>
+</p>
+"""
+
 html_theme = 'alabaster'
+
+# For documentation on the available options that the Alabaster theme provides,
+# see https://alabaster.readthedocs.io/en/latest/customization.html
 html_theme_options = {
     'logo': '${MATERIALX_LOGO_FILENAME}',
-    'description': '<b>MaterialX</b> &ndash; An open standard for the exchange of rich material and look-development content across applications and renderers.',
-    'github_button': True,
+    'description': about,
+    'github_button': False,
     'github_user': 'AcademySoftwareFoundation',
     'github_repo': 'MaterialX',
     'extra_nav_links': {
+        'MaterialX.org': 'https://materialx.org/',
         'MaterialX C++ API Docs': 'https://materialx.org/docs/api/index.html',
+        'MaterialX Specification': 'https://materialx.org/Specification.html',
     },
+    # Style colors
+    'sidebar_hr': 'var(--separator-color)',
+    'sidebar_search_button': 'var(--separator-color)',
+}
+
+# Use a custom navigation Jinja template instead of the default 'navigation.html'
+# in order to set a maximum depth in the table of contents in the sidebar
+html_sidebars = {
+    '**': [
+        'about.html',               # standard
+        'sphinx-navigation.html',   # custom
+        'searchbox.html',           # standard
+    ]
 }