Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
This PR adds support for generating Python API documentation in HTML format using Sphinx from the MaterialX Python that are built in the `lib/` directory. A new CMake build option named `MATERIALX_BUILD_PYTHON_DOCS` allows developers to turn generating Python API documentation on. When `MATERIALX_BUILD_PYTHON_DOCS` is set to `ON`, `MATERIALX_BUILD_PYTHON` is set to `ON` as well, ensuring we have Python modules for which to build the Python API docs. The core functionality of generating Python API documentation lives in a new directory named `documents/PythonAPI/`. It is controlled with a new `CMakeLists.txt` file in that directory, which defines a new target named `MaterialXDocsPython`, similar to the existing target `MaterialXDocs` that generates API documentation for the MaterialX C++ API. To facilitate the curation and addition of docstrings in the implementation files within `source/PyMaterialX/`, this PR adds a new helper macro named `PYMATERIALX_DOCSTRING` that allows developers of Python modules to define docstrings using the following pattern: ```cpp PYMATERIALX_DOCSTRING(R"docstring( ...markdown text here... )docstring"); ``` Revised docstrings for modules and classes are to be added in subsequent PRs separately. Documentation in markdown format from the existing `DeveloperGuide` is integrated into the new Python API documentation by way of symlinking the four main `.md` files into the `documents/PythonAPI/sources/` directory from which Sphinx generates the resulting HTML documentation. Warnings that are issued when generating the documentation via Sphinx are to be addressed in a separate PR for the markdown files: AcademySoftwareFoundation#2037 To build the docs from scratch on macOS, I've used the following build script, naming it `build.sh` in the `MaterialX` checkout directory: ```bash echo build.sh: Updating Git submodules... git submodule update --init --recursive python3 -m venv /tmp/venv source /tmp/venv/bin/activate.csh echo build.sh: Installing dependencies... python3 -m pip install myst_parser # https://pypi.org/project/myst-parser/ echo build.sh: Making build directory and changing into it... mkdir build cd build echo build.sh: Configuring... cmake .. \ --fresh \ -DCMAKE_OSX_SYSROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX15.0.sdk \ -DMATERIALX_BUILD_PYTHON=ON \ -DMATERIALX_BUILD_VIEWER=ON \ -DMATERIALX_BUILD_GRAPH_EDITOR=ON \ -DMATERIALX_BUILD_DOCS=ON \ -DMATERIALX_BUILD_PYTHON_DOCS=ON \ -DMATERIALX_BUILD_TESTS=ON \ && \ echo build.sh: Building... \ && \ cmake --build . -j 8 \ && \ echo build.sh: Building target MaterialXDocs... \ && \ cmake --build . --target MaterialXDocs \ && \ echo build.sh: Building target MaterialXDocsPython... \ && \ cmake --build . --target MaterialXDocsPython \ && \ afplay /System/Library/Sounds/Blow.aiff deactivate ``` The build output currently ends with the following messages: ```python The parsed MaterialX Python API consists of: * 11 modules * 48 functions * 139 classes * 1175 methods * 6 exception types WARNING: 48 functions look like they do not have docstrings yet. WARNING: 1019 methods look like they do not have docstrings yet. WARNING: 32 functions look like their parameters have not all been named using `py::arg()`. WARNING: 499 methods look like their parameters have not all been named using `py::arg()`. build succeeded, 168 warnings. The HTML pages are in .. [100%] Built target MaterialXDocsPython ``` Split from AcademySoftwareFoundation#1567. Update AcademySoftwareFoundation#342. Signed-off-by: Stefan Habel <[email protected]>
- Loading branch information
1 parent
0653e1d
commit 6c8efaf