Sphinx Python Documentation

[jstone-lucasfilm]

Add support for the generation of Sphinx documentation for MaterialX Python, using the approach described here:

https://pybind11.readthedocs.io/en/stable/advanced/misc.html#generating-documentation-using-sphinx

[StefanHabel]

I'd like to take a stab at this for the ASWF Dev Days 2023.

If I’m understanding this right, the work here roughly consists of two parts:

1. Integrating a Sphinx build of the MaterialX Python API documentation into the MaterialX CMake build
2. Adding/extending docstrings for MaterialX Python bindings using pybind11

While it may not be possible/feasible to add/curate docstrings for all MaterialX Python bindings during Dev Days, it should be possible to lay the foundation for building API documentation using Sphinx on the day.

Proposed approach/outcome:

• An optional extra build target similar to the existing cmake --build . --target MaterialXDocs (which uses doxygen to generate C++ API documentation), possibly named MaterialXDocsPython.
• Documentation in HTML format that is generated in a sibling folder next to the existing C++ API documentation (as opposed to living in the same html folder).

Proposed artifacts:

1. A new CMake module at cmake/modules/FindSphinx.cmake to be able to find the sphinx-build executable (Windows: sphinx-build.exe) from documents/CMakeLists.txt using find_package(Sphinx).
   • cf. https://eb2.co/blog/2012/03/sphinx-and-cmake-beautiful-documentation-for-c-projects/
   • cf. https://www.vortech.nl/en/integrating-sphinx-in-cmake/
2. Modifications to documents/CMakeLists.txt to create a new build target named MaterialXDocsPython, which would run sphinx-build to generate Python API developer documentation, in a directory that is separate to the existing doxygen-generated html documentation, e.g. named html-sphinx.
   • https://www.sphinx-doc.org/en/master/tutorial/getting-started.html
3. A Sphinx configuration template file (e.g. documents/sphinx-conf.py.in) that would be filled with values of configuration variables like MATERIALX_LIBRARY_VERSION as part of the build, in order to generate the conf.py file that sphinx-build uses.
   • This would be similar to the existing developer/Doxyfile.in from which documents/CMakeLists.txt generates Doxyfile for configuring the doxygen run.
   • https://www.sphinx-doc.org/en/master/usage/configuration.html
4. Integration of existing developer guide contents in Markdown format from documents/DeveloperGuide/ into the Sphinx-generated Python API documentation, e.g. using the myst_parser extension:
   • https://www.sphinx-doc.org/en/master/usage/markdown.html
   • GraphEditor.md
   • MainPage.md
   • ShaderGeneration.md
   • Viewer.md
5. A new paragraph in the Building API Documentation section in documents/DeveloperGuide/MainPage.md to describe how to build the Python API documentation using Sphinx.
6. Integration of docstrings from MaterialX Python bindings that are defined in source/PyMaterialX/ from compiled Python C extensions, e.g. from lib/PyMaterialXCore.cpython-312-darwin.so etc.
   • PyMaterialXCore/
   • PyMaterialXFormat/
   • PyMaterialXGenGlsl/
   • PyMaterialXGenMdl/
   • PyMaterialXGenMsl/
   • PyMaterialXGenOsl/
   • PyMaterialXGenShader/
   • PyMaterialXRender/
   • PyMaterialXRenderGlsl/
   • PyMaterialXRenderMsl/
   • PyMaterialXRenderOsl/

[StefanHabel]

I'd like to continue our work on this from last year’s ASWF Dev Days next week:
#1567