Writing Documentation¶

How this doc site works and how to add to it.

Stack¶

MkDocs + Material theme — Markdown in, static site out. Config in mkdocs.yml at the repo root.
mkdocstrings — renders API reference pages from docstrings via static analysis (griffe). It never imports the code, so modules that only run inside Maya/Blender/Premiere document fine.

Local workflow¶

venv\Scripts\python -m mkdocs serve   # live-reload at http://localhost:8000

Edit any .md under docs/ and the browser refreshes automatically.

Adding a page¶

Create the .md file under docs/ (e.g. docs/guides/my-feature.md).
Add it to the nav: section of mkdocs.yml.

Adding an API reference page¶

Create a page containing a mkdocstrings directive:

# alc.services.media

::: alc.services.media.video

The ::: directive pulls in the module, its classes, and their docstrings. Options (member order, source visibility) are set globally in mkdocs.yml and can be overridden per-directive.

Docstring style¶

Google style:

def resolve(self, software: str) -> Recipe:
    """Resolve the recipe for a software, with cross-DCC fallback.

    Args:
        software: The requesting DCC (e.g. ``blender``).

    Returns:
        The matched Recipe, possibly from a fallback DCC.

    Raises:
        KeyError: If no DCC implements this (task, phase).
    """

Keeping docs in sync with code¶

Run /update-docs (a Claude Code command, .claude/commands/update_docs.md) after building a feature. It diffs code changed since the last sync (tracked in docs/.docs-sync), updates only the affected pages, rebuilds, and advances the marker — so each run is incremental. --dry-run previews without changing anything; --all audits the whole tree. It won't commit for you.

The /handbook copy the app serves is the built site, so run mkdocs build after a docs change for it to show up.

Conventions¶

Specs (design docs written before/while building a feature) go in docs/specs/ and get a nav entry under Specs. They are historical documents — don't retro-edit them; write a guide instead once the feature settles.
Guides (how to use a feature) go in docs/guides/.
Architecture pages describe load-bearing concepts that rarely change.
Mermaid diagrams work in any page via ```mermaid fences.