Documentation Guide

This guide explains how to build, preview, and publish Super Pocket’s documentation with Sphinx locally and Read the Docs (RTD) in production.

Local Sphinx Workflow

  1. Create a virtual environment (recommended):

    python -m venv .venv
source .venv/bin/activate

  2. Install the documentation dependencies:

    pip install -r docs/requirements.txt

  3. Build the HTML site:

    cd docs
make html
# View it
open _build/html/index.html  # macOS

  4. Enable live reload while editing:

    make livehtml  # Requires sphinx-autobuild

  5. Lint links and references before pushing:

    make linkcheck

Autodoc & API Pages

  • docs/conf.py already enables autodoc and autosummary.

  • Add new modules to docs/api.rst and docs/modules.rst so Sphinx and RTD pick them up.

  • Keep docstrings in English and prefer Google-style formatting for best rendering.

  • When adding modules, ensure they are importable (use if TYPE_CHECKING guards if heavy dependencies are optional).

Read the Docs Configuration

Super Pocket is published at https://pocketdocs.readthedocs.io/. To keep builds green:

  • Project settings

    • Repository: main branch

    • Documentation type: Sphinx HTML

    • Python version: 3.11+

    • Install requirements: docs/requirements.txt (configured under Advanced settings → Python → Requirements file)

  • Build command

    RTD automatically invokes sphinx-build -b html docs/ docs/_build/html. No custom command is needed as long as conf.py lives in docs/.

  • Environment variables

    Add any secrets (for example API keys used in code examples) through the RTD dashboard. Do not commit them to the repo.

  • Versioning

    Tag releases (v1.0.2, etc.) so RTD can produce versioned docs. Enable the “Activate on tag” option if you want automatic builds per release.

Pre-Publish Checklist

Run these commands locally before opening a PR that touches documentation:

# Clean previous builds to avoid stale assets
make -C docs clean

# Fails on warnings to mimic RTD's stricter settings
sphinx-build -n -W --keep-going -b html docs/ docs/_build/html

# Verify external links (can be slow, so only when needed)
make -C docs linkcheck

Troubleshooting

  • Module import errors: Confirm sys.path in docs/conf.py points to the repo root. Keep runtime-only dependencies optional or mock them in docs builds.

  • Theme/CSS not applied on RTD: Ensure files under docs/_static are tracked and referenced via html_css_files.

  • Missing API entries: Update docs/api.rst or docs/modules.rst and rebuild with make html to refresh the autosummary stubs.

  • Build succeeds locally but fails on RTD: Re-run builds using sphinx-build -n -W to treat warnings as errors and catch the same issues locally.

Next Steps