Add docs Claude Code skill

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: mfosterw

.claude/skills/docs/SKILL.md

@@ -0,0 +1,116 @@
+---
+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 activitypub 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.activitypub.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:
+
+```python
+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