API Documentation Automation

API Documentation Automation

Summary

Automate the generation of API documentation stubs and HTML browsable outputs from Python source code using Sphinx and sphinx-apidoc. This skill bridges repository source files to machine-readable and human-browsable API reference documentation.

When to use

When you have a Python package with docstrings in the source code and need to generate comprehensive, browsable HTML API documentation. Apply this skill after installing package dependencies when the documentation source tree exists but API stubs have not yet been generated, or when documentation needs to be rebuilt after source code changes.

When NOT to use

• Source code lacks docstrings or uses a non-Sphinx documentation system (e.g., MkDocs, pdoc); use the appropriate tool for your documentation framework instead.
• Documentation is already built and only minor updates to display are needed; incrementally modify .rst sources rather than regenerating from scratch.
• Python package is not installed or does not follow standard module structure; ensure the package can be imported before running sphinx-apidoc.

Inputs

• requirements.txt (Python dependency file)
• Python package source directory (e.g., ../dreams module with docstrings)
• Sphinx configuration file (conf.py)
• Sphinx source files (.rst files)
• tutorials directory (optional but recommended)

Outputs

• _build/html/ directory (compiled HTML documentation)
• _build/html/index.html (main documentation entry point)
• API stubs (.rst files generated by sphinx-apidoc)
• Browsable API reference pages

How to apply

First, install Python dependencies listed in requirements.txt using pip. Then create a symbolic link from the tutorials folder to the documentation directory to ensure tutorials are accessible in the build. Next, run sphinx-apidoc to recursively scan the Python package source directory (e.g., ../dreams) and generate reStructuredText stub files in the current directory. Finally, execute make html to invoke the Sphinx build system, which processes the generated stubs and source files to produce compiled HTML documentation in the _build/html output directory. The resulting directory contains an index.html entry point for browser navigation.

Related tools

• Sphinx (Compiles reStructuredText documentation sources into HTML and manages documentation build system via make html) — https://www.sphinx-doc.org/
• sphinx-apidoc (Scans Python package source directory and automatically generates API documentation stub files (.rst) from module and function docstrings) — https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html
• pip (Installs Python package dependencies from requirements.txt before documentation build) — https://pip.pypa.io/

Examples

cd docs && pip install -r requirements.txt && ln -s ../tutorials tutorials && sphinx-apidoc -o . ../dreams && make html && open _build/html/index.html

Evaluation signals

• Verify that _build/html/ directory exists and contains index.html and module-specific .html files
• Open _build/html/index.html in a browser and confirm all API modules, classes, and functions are listed with docstrings rendered as formatted text
• Check that generated API stub files (.rst) in the documentation directory match the source package structure (e.g., dreams.rst, dreams.module1.rst for submodules)
• Confirm that tutorials folder is linked and accessible from the browsable documentation (e.g., a 'Tutorials' link resolves without 404 errors)
• Validate that no Sphinx build warnings or errors are reported during make html execution (warnings are acceptable if they do not prevent HTML generation)

Limitations

• sphinx-apidoc requires source code to use standard Python docstring formats (Google, NumPy, or reStructuredText); inconsistent or missing docstrings result in sparse or empty API pages.
• The build assumes a conventional Sphinx project layout with conf.py and Makefile in the documentation directory; non-standard configurations may require manual adjustments to sphinx-apidoc options or make invocation.
• Symbolic linking (ln -s) is Unix-only; Windows environments must use alternatives such as mklink or copy the tutorials folder instead.
• Large packages with hundreds of modules can produce slow sphinx-apidoc scans; filtering specific modules via sphinx-apidoc flags may be needed for performance.
• Generated HTML is static; dynamic content or real-time API queries must be added post-hoc via JavaScript or custom Sphinx extensions.

Evidence

• [methods] Generate API documentation stubs by running sphinx-apidoc to scan the ../dreams module and output documentation source files.: "Generate API documentation stubs by running sphinx-apidoc to scan the ../dreams module and output documentation source files"
• [methods] Build HTML documentation using make html, which processes Sphinx source files and generates the browsable output in _build/html/.: "Build HTML documentation using make html, which processes Sphinx source files and generates the browsable output in _build/html/"
• [methods] sphinx-apidoc -o . ../dreams && make html: "sphinx-apidoc -o . ../dreams && make html"
• [methods] Install Python dependencies from requirements.txt using pip.: "Install Python dependencies from requirements.txt using pip"
• [methods] Create a symbolic link from the tutorials folder to the current documentation directory using ln -s.: "Create a symbolic link from the tutorials folder to the current documentation directory using ln -s"