API Documentation

This documents the way how to build and modify API documentation using Sphinx and AutoAPI. Ground for documentation should be directly in sources - in docstrings and markdowns. Sphinx and AutoAPI will crawl over them and generate RST files that are in turn used to generate HTML documentation. For docstrings we prefer "Napoleon" or "Google" style docstrings, but RST is also acceptable mainly in cases where you need to use Sphinx directives.

Using only docstrings is not really viable as some documentation should be done on higher level - like overview of some modules/functionality and so on. This should be done directly in RST files and committed to repository.

Configuration

Configuration is done in /docs/source/conf.py. The most important settings are:

• autodoc_mock_imports: add modules that can't be actually imported by Sphinx in running environment, like nuke, maya, etc.
• autoapi_ignore: add directories that shouldn't be processed by AutoAPI, like vendor dirs, etc.
• html_theme_options: you can use these options to influence how the html theme of the generated files will look.
• myst_gfm_only: are Myst parser option for Markdown setting what flavour of Markdown should be used.

How to build it

You can run:

cd .\docs
make.bat html

on linux/macOS:

cd ./docs
make html

This will go over our code and generate .rst files in /docs/source/autoapi and from those it will generate full html documentation in /docs/build/html.

During the build you may see tons of red errors that are pointing to our issues:

1. Wrong imports - Invalid import are usually wrong relative imports (too deep) or circular imports.
2. Invalid docstrings - Docstrings to be processed into documentation needs to follow some syntax - this can be checked by running pydocstyle that is already included with OpenPype
3. Invalid markdown/rst files - Markdown/RST files can be included inside RST files using .. include:: directive. But they have to be properly formatted.

Editing RST templates

Everything starts with /docs/source/index.rst - this file should be properly edited, Right now it just includes readme.rst that in turn include and parse main README.md. This is entrypoint to API documentation. All templates generated by AutoAPI are in /docs/source/autoapi. They should be eventually committed to repository and edited too.

Steps for enhancing API documentation

1. Run /docs/make.bat html
2. Read the red errors/warnings - fix it in the code
3. Run /docs/make.bat html - again until there are no red lines
4. Edit RST files and add some meaningful content there

Resources

• ReStructuredText on Wikipedia
• RST Quick Reference
• Sphinx AutoAPI Documentation
• Example of Google Style Python Docstrings
• Sphinx Directives