Tips for Developers (2): API documentation

Generate API documentation

To generate the API documentation automatically from inline comments using Python Docstrings, you need to follow below steps. The original instruction was provided by @tomvothecoder and edited by @lee1043. (2023-06)

Enable sphinx extentions

Enable “sphinx.etc.autodoc”, “sphinx.ext.autosummary”, and “sphinx.ext.napoleon” (source)

• Example: xCDAT uses the NumPy style docstring, which is the common format for scientific Python libraries. sphinx.ext.napoleon parses Google/NumPy docstring.
• (Optional) Use the autoDocstring plugin in VSCode which makes generating docstrings super easy.

Configure these extensions (example)

• Autosummary
• Autodoc
• Napoleon

Deploy

Add an api.rst page to Sphinx that lists the APIs you want to show in the docs

• Example api.rst
• Make sure it is included in the index.rst

Resources

Additional tutorial is available for further information.