Documentation

Documentation

This skill helps set up and maintain project documentation using Sphinx for publication on readthedocs.org.

When to Use This Skill

• Setting up Sphinx documentation for a new project
• Updating API reference after adding new features
• Creating user guides and installation instructions
• Updating changelog after releases
• Fixing documentation build issues

Documentation Structure

docs/
  _static/          # Static files (images, etc.)
  _templates/       # Custom templates (optional)
  api/              # API reference pages
    app.md
    exceptions.md
    plugins.md
    ...
  development/      # Development guides
    contributing.md
    changelog.md
  conf.py          # Sphinx configuration
  index.md          # Documentation home
  installation.md   # Installation guide
  quickstart.md     # Quick start guide
  requirements.txt  # Sphinx dependencies
  Makefile          # Build commands

Workflow

1. Check Documentation Setup

Verify documentation structure exists:

• docs/conf.py - Sphinx configuration
• docs/index.md - Documentation home
• docs/Makefile - Build commands
• docs/requirements.txt - Dependencies

If missing, create standard Sphinx setup.

2. Update API Reference

When adding new public APIs:

1. Create or update docs/api/{module}.md
2. Use autodoc directives for automatic documentation
3. Include usage examples
4. Add to docs/index.md toctree

3. Update Changelog

When completing features:

1. Add entry to docs/development/changelog.md
2. Include: date, type (Added/Changed/Fixed/Removed), description
3. Reference issues/PRs if applicable

4. Update Guides

When adding new features:

1. Update docs/quickstart.md if API changes
2. Add examples to docs/api/{module}.md
3. Update CLAUDE.md if workflow changes

5. Build and Verify

Run make docs and verify:

• No warnings or errors
• All links resolve
• API reference is complete

Sphinx Configuration

Standard conf.py for Python projects:

# Configuration file for the Sphinx documentation builder.

import os
import sys
sys.path.insert(0, os.path.abspath("../src"))

project = "project-name"
copyright = "YEAR, Author"
author = "Author"

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.autosummary",
    "sphinx.ext.napoleon",
    "sphinx.ext.viewcode",
    "sphinx.ext.intersphinx",
    "myst_parser",
]

html_theme = "sphinx_rtd_theme"

# Autodoc settings
autodoc_member_order = "bysource"
autodoc_default_options = {
    "members": True,
    "undoc-members": True,
    "show-inheritance": True,
}

# Intersphinx mappings
intersphinx_mapping = {
    "python": ("https://docs.python.org/3", None),
}

Changelog Format

Follow Keep a Changelog:

## [version] - YYYY-MM-DD

### Added
- New feature X

### Changed
- Modified feature Y

### Fixed
- Bug fix for Z

### Removed
- Deprecated feature W

Common Issues

Missing docs/Makefile

Create with standard Sphinx Makefile:

SPHINXOPTS    ?=
SPHINXBUILD   ?= sphinx-build
SOURCEDIR     = .
BUILDDIR      = _build

help:
	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

%: Makefile
	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

uv Environment Detection

If make docs fails with "No virtual environment detected", ensure uv is being used:

# Standard docs target (from python-project skill)
docs: env-dev ## Build HTML documentation
	cd docs && uv run sphinx-build -M html . _build

docs-view: docs ## Build and open documentation in browser
	open docs/_build/html/index.html

Note: Use uv run sphinx-build instead of make html — it works without requiring a separate docs/Makefile.

Pre-commit Checklist

Before committing documentation:

1. Run make docs - no errors
2. Check all new APIs documented
3. Update changelog
4. Update screenshot if showcase changed
5. Ask user to verify screenshot

Source: christophevg/c3 — distributed by TomeVault.