sphinx-documentation-generation-and-api-reference-inclusion

Sphinx Documentation Generation and API Reference Inclusion

Summary

Build and validate Sphinx documentation for a Python library, ensuring that utility functions and their docstrings are correctly rendered in the generated API reference. This workflow integrates Numpy-style docstrings with Sphinx to produce HTML documentation that exposes the library's public API.

When to use

After implementing or modifying utility functions in a library subpackage (e.g., cooltools.lib), use this skill to verify that the function is discoverable in the generated API documentation, that its docstring is properly formatted, and that the documentation build succeeds without warnings or errors.

When NOT to use

• Function docstrings are written in a non-Numpy style (e.g., Google or reST style) without Sphinx extensions configured to parse them — the resulting API documentation will render incorrectly or be missing parameter details.
• The target function has not been added to the library's public API interface or init.py imports — Sphinx will not discover it for inclusion in the reference.
• The Sphinx configuration is not set up to parse Python docstrings (e.g., sphinx.ext.autodoc or sphinx.ext.napoleon is not enabled) — no docstring content will be extracted.

Inputs

• Python source code files with function definitions in a library subpackage (e.g., cooltools/lib/adaptive_coarsegrain.py)
• Numpy-style docstrings attached to functions and classes
• Sphinx configuration file (conf.py)
• Documentation source files (e.g., docs/api.rst or equivalent)

Outputs

• Generated HTML documentation (docs/_build/html/)
• API reference pages listing functions, classes, and their docstrings
• Build report indicating successful or failed Sphinx compilation
• Documentation validation report confirming function visibility and formatting

How to apply

First, ensure that all utility functions use Numpy-style docstrings, which Sphinx can automatically parse and render into the API reference. Run make docs from the repository root to trigger the Sphinx build process, which will generate HTML documentation from the source code and docstrings. Inspect the generated HTML files in the build directory (typically docs/_build/html/) to confirm that the target function appears in the appropriate API section (e.g., cooltools.lib) with correctly formatted parameters, returns, and examples. If the function is missing or malformed, verify that (1) the module is correctly imported in the documentation configuration, (2) the docstring follows Numpy format conventions, and (3) no Sphinx warnings were emitted during the build. Re-run the build after corrections and re-inspect the HTML output.