The Complete Production SOP: How to Deploy and Run Sphinx Python autodoc & Read the Docs in Autonomous AI Agents
Step-by-step SOP to install and run Sphinx Python autodoc & Read the Docs in Codex, Claude Code, and Cursor. Automate Python API docs with zero hallucination.
Technical Overview & Architectural Context
Autonomous coding agents frequently encounter friction when tasked with generating Python API documentation. When unconstrained, agents often construct raw Markdown files manually, omit sys.path configuration in Sphinx's conf.py, produce broken cross-package references, or fail to parse Google/NumPy docstring conventions with Sphinx Napoleon. This leads to broken builds, missing class member listings, and unmaintainable documentation trees that drift immediately from source code. The sphinx-python-autodoc-rtd skill eliminates these failure modes by enforcing a strict procedural Standard Operating Procedure (SOP). It guides autonomous coding agents (Codex, Claude Code, Cursor, Windsurf) through deterministic execution boundaries: directory bootstrapping with sphinx-quickstart, automated stubs creation via sphinx-apidoc, proper injection of sphinx_rtd_theme and sphinx.ext.napoleon, and strict local compilation validation with 'make html'. By restricting workspace boundaries and standardizing conf.py mutations, the skill prevents hallucinations and ensures production-ready Read the Docs builds.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Mount the SKILL.md definition into the agent skill directory to inject deterministic doc generation SOPs.
Autonomous runtimes parse local manifests located in `.agents/skills` or `.claude/skills`. Installing this skill enables runtime trigger detection whenever you ask the agent to configure documentation or compile autodoc references.
mkdir -p .agents/skills/sphinx-python-autodoc-rtd && curl -fsSL https://askills.dev/api/skills/sphinx-python-autodoc-rtd/raw -o .agents/skills/sphinx-python-autodoc-rtd/SKILL.md---
name: "sphinx-python-autodoc-rtd"
description: "Automate Python package API documentation with Sphinx autodoc and Read the Docs theme."
metadata:
author: "Sphinx Team"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "generate python api docs sphinx"
- "configure sphinx autodoc"
- "setup read the docs theme"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---Instruct Claude Code or Cursor to read SKILL.md as a project rule so it avoids hallucinating ad-hoc MkDocs or custom static sites when Sphinx is requested.
Ensure .agents/skills is not excluded by .cursorignore or Claude Code file watcher settings.
Sphinx Dependencies & Path Configuration
Ensure Sphinx, Napoleon, and Read the Docs theme dependencies are available in the local virtual environment.
Autodoc dynamically imports Python modules to inspect docstrings. The runtime agent must verify that dependencies are declared in pyproject.toml or requirements-dev.txt and that sys.path in docs/source/conf.py correctly resolves the src package.
pip install sphinx sphinx-rtd-theme sphinx-autodoc-typehintsimport os
import sys
sys.path.insert(0, os.path.abspath('../../src'))
project = 'MyPackage'
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinx.ext.viewcode',
'sphinx_autodoc_typehints',
]
html_theme = 'sphinx_rtd_theme'Add `autodoc_mock_imports = [...]` in conf.py for C-extensions or cloud libraries to prevent import failures in sandbox runners.
Failing to set sys.path.insert(0, os.path.abspath('../../src')) is the primary cause of 'autodoc: failed to import module' errors.
Intent Matching & Trigger Invocation
Invoke the agent using trigger phrases that activate the autodoc scaffolding SOP.
Use deterministic phrases specified in the skill metadata ('generate python api docs sphinx', 'configure sphinx autodoc', 'setup read the docs theme'). The agent interprets these triggers to orchestrate sphinx-apidoc and link index.rst modules.
Specify docstring formatting preferences (e.g., 'Using Google docstring format') in the prompt to prime Sphinx Napoleon parsing.
Avoid vague prompts like 'write docs for my code', which tempt the agent to write verbose manual Markdown instead of automated Sphinx references.
Build Verification & HTML Quality Gate
Execute the Sphinx build pipeline and enforce a clean exit code before accepting changes.
The skill enforces running `sphinx-build` or `make html` with the `-W --keep-going` flags. This treats docstring formatting warnings as errors while compiling the entire set, ensuring zero broken links or unparsed signatures.
sphinx-build -b html -W --keep-going docs/source docs/_build/htmlSPHINXOPTS ?= -W --keep-going
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
BUILDDIR = _build
html:
@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)Use `docs/_build/html` in your `.gitignore` to avoid committing megabytes of compiled assets to version control.
The `-W` flag turns warnings into errors; unclosed backticks in docstrings will abort the build until repaired.
Real-World Scenario: Automated API Documentation Generation for Python Data Engine
“Run the sphinx-python-autodoc-rtd skill to generate python api docs sphinx for our 'core_engine' package located in src/core_engine. Setup read the docs theme and ensure autodoc and napoleon are enabled.”
Runtime Troubleshooting & Failure Modes
Root Cause: Sphinx cannot locate the package root directory because docs/source/conf.py lacks the appropriate sys.path resolution relative to the repository workspace.
import os
import sys
sys.path.insert(0, os.path.abspath('../../src'))Root Cause: The sphinx-rtd-theme package is either not installed in the agent's current Python runtime environment or not registered as an extension in newer Sphinx versions.
pip install sphinx-rtd-theme && sed -i '' "s/extensions = \[/extensions = [\n 'sphinx_rtd_theme',/" docs/source/conf.pyFrequently Asked Questions (Sphinx Python autodoc & Read the Docs SOP)
Q:Can I use Sphinx Python autodoc & Read the Docs across Codex, Claude Code, and Cursor simultaneously?
Yes. The skill conforms to the universal SKILL.md specification supported across all modern agent runtimes. By placing the file in `.agents/skills/sphinx-python-autodoc-rtd/SKILL.md`, Codex, Claude Code, Cursor, and Windsurf can read and apply the same deterministic rules.
Q:How does Sphinx Python autodoc & Read the Docs prevent context window overflow during long agent sessions?
By establishing concise procedural boundaries and deterministic validation gates rather than polluting system prompts with redundant rules. Instead of dumping hundreds of raw docstrings into the LLM context, the agent offloads reflection to sphinx-apidoc and only reviews compilation warnings.
Q:Does this skill require escalated root or container permissions?
No. It is audited with a security score of 98/100 and runs safely within workspace-scoped sandboxes. It requires file reading and writing within the workspace directory and local shell execution only to invoke sphinx-build commands.
Ready to equip your autonomous agent with Sphinx Python autodoc & Read the Docs?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.