SKILL.md

name	docs
description	Update, review, or build the Sphinx documentation for Democrasite
disable-model-invocation	true
argument-hint	[what to update or check, e.g. 'review for accuracy' or 'add social section']

Task

$ARGUMENTS

Documentation structure

docs/
├── conf.py                  — Sphinx config (theme, extensions, Django setup)
├── index.rst                — Master toctree (README, CONTRIBUTING, howto, users, webiscite, api/)
├── README.rst               — Project overview (mirrors root README)
├── CONTRIBUTING.rst         — Dev setup and contribution guide
├── howto.rst                — Instructions for building and writing docs
├── users.rst                — Users app overview (minimal; relies on autodoc)
├── webiscite.rst            — Core app narrative (pipeline, bill lifecycle)
└── api/                     — Auto-generated RST files (do not edit manually)
    ├── democrasite.rst
    ├── democrasite.webiscite.rst
    ├── democrasite.webiscite.models.rst
    ├── democrasite.webiscite.managers.rst
    ├── democrasite.webiscite.tasks.rst
    ├── democrasite.webiscite.webhooks.rst
    ├── democrasite.webiscite.constitution.rst
    ├── democrasite.webiscite.views.rst
    ├── democrasite.webiscite.api.rst
    ├── democrasite.users.rst
    ├── democrasite.social.rst
    └── … (one file per module)

Key make commands

All run from the docs/ directory (or with make -C docs <target>):

Command	What it does
make apidocs	Regenerate all docs/api/*.rst from source using sphinx-apidoc. Run this whenever Python modules are added or removed.
make livehtml	Build docs and serve with live reload at http://localhost:9000. Requires the docs Docker container (docker compose -f docker-compose.docs.yml up).
make clean	Remove _build/ and api/ directories for a fresh build.
make html	One-off HTML build into _build/html/.

To serve with live reload locally (in Docker):

docker compose -f docker-compose.docs.yml up

To regenerate API docs locally (sphinx-apidoc must be installed):

make -C docs apidocs

What is auto-generated vs. manual

• docs/api/ — fully auto-generated by make apidocs (sphinx-apidoc). Never edit these files directly; edit the Python docstrings instead, then re-run make apidocs.
• docs/webiscite.rst and docs/users.rst — manually maintained narrative docs. Keep these in sync with code changes (especially webiscite.rst for the PR pipeline and bill lifecycle).
• docs/CONTRIBUTING.rst and docs/howto.rst — manually maintained.

Docstring style

Use Google-style docstrings (supported via the Napoleon extension). Example:

def my_function(arg: int) -> str:
    """One-line summary.

    Longer description if needed.

    Args:
        arg: Description of the argument.

    Returns:
        Description of the return value.

    Raises:
        ValueError: When and why.
    """

Line length: 88 characters (enforced by ruff). Wrap long docstring lines to stay within this limit.

Steps for common tasks

Reviewing docs for accuracy

1. Read docs/webiscite.rst and cross-check function/class references against actual source code
2. Check that docstrings in democrasite/webiscite/managers.py, models.py, tasks.py, webhooks.py, and constitution.py have correct parameter names and return descriptions
3. Run make apidocs if modules have been added or removed since the last regeneration
4. Run just lint to confirm no ruff line-length violations were introduced

Adding or updating narrative docs

1. Edit the relevant .rst file in docs/ (not under docs/api/)
2. Use Sphinx cross-references for code identifiers:
   • :class:\~democrasite.webiscite.models.Bill`` — class link
   • :func:\~democrasite.webiscite.tasks.submit_bill`` — function link
   • :meth:\~democrasite.webiscite.webhooks.PullRequestHandler.opened`` — method link
3. Verify the build: docker compose -f docker-compose.docs.yml up

Adding a new Python module

1. Write a module-level docstring at the top of the file
2. Run make apidocs to regenerate docs/api/ — this creates the new RST file and adds it to the relevant package toctree automatically
3. Commit the updated docs/api/ files alongside the new module

Updating docs after refactoring

1. Update any cross-references in docs/webiscite.rst or docs/users.rst that point to renamed/removed identifiers
2. Update affected docstrings in source files
3. Run make apidocs if the module structure changed (files added/removed)
4. Run just lint to verify no line-length violations

Published docs

• ReadTheDocs URL: https://cookiestocracy.readthedocs.io/en/latest/
• Builds automatically on push to the main branch