Authoring and reviewing documentation

AEAT is a Spanish tax-filing application. This guide shows you how to make a documentation change and take it through review. Four documentation surfaces exist: repository markdown, in-source docstrings, and two generated references — one for the application programming interface (API) and one for the command-line interface (CLI).

Choose the right surface

Where you make a change depends on what you’re changing:

  • Repository markdown is hand-written. Edit the README or a guide under docs/ directly.

  • Docstrings are the single source for the API reference. Edit the docstring in the source, and let Sphinx (the documentation build tool) render it. Never copy a signature into prose by hand.

  • The API reference is generated from the source modules by the dev.docs.apidocs tool. It writes stub pages (placeholder reference files); don’t edit those pages by hand — regenerate them.

  • The CLI reference is generated from the command tree (the full set of CLI commands and subcommands). Don’t edit it; regenerate it with the commands that follow.

Definitions of generation terms

When working with generated documentation, understand the following terminology:

  • apidocs: The dev.docs.apidocs command-line tool, located at dev/docs/apidocs/. This is the project’s API reference stub builder, which crawls the codebase module tree to determine the structure of the API and generates the corresponding reference files.

  • stub: A reference stub page is an autogenerated, placeholder RestructuredText (.rst) file under docs/api/. Each stub file corresponds to a Python module or package and contains the automodule directives that instruct Sphinx to pull the live docstring from the code. Stubs are checked into the repository but must never be edited by hand.

To rebuild the generated surfaces and verify them, run:

python -m dev.docs.apidocs scaffold  # writes the API stub pages
just docs                        # builds the full documentation site
just docs-serve                  # serves the site with live reload (auto-picks a free port)
just docs-check                  # validates cross-references, stubs, and CLI output

just docs-serve opens a preview that rebuilds and refreshes the browser whenever a page under docs/ or a docstring under src/aeat/ changes. It binds every interface on a non-default port (so a container, VM, or LAN peer can reach it) and auto-picks a free port; pass just docs-serve 9000 to pin one. Running it a second time attaches to the already-running preview instead of colliding with it. Adding or removing a module still needs python -m dev.docs.apidocs scaffold to refresh the stub set.

just docs-check fails on a broken cross-reference, a missing stub, or a command reference that no longer matches the commands.

Take a narrative change through review

A change to the README or a guide under docs/ moves through a staged review. Each stage has a distinct reviewer, and each completes before the next begins:

  1. Wireframe. Outline the document as titles and section intents. Assign each page a Diataxis type — Diataxis is a documentation framework that sorts pages into four kinds: tutorial, how-to, reference, or explanation.

  2. Refinement. A reviewer with no project context reads only the wireframe and confirms a newcomer would understand what each section delivers. Revise until every section passes.

  3. Context. Researchers gather the facts, commands, paths, and source locations each section needs.

  4. Drafting. Authors write each section from the gathered context and the prose-style rules (.claude/skills/vaultspec-documentation/references/prose-style-rules.md).

  5. Technical review. Reviewers verify every command, flag, path, and class name against the code.

  6. Editorial review. A reviewer with no project context checks the writing against the prose-style rules (same reference as step 4).

  7. Approval. The change lands once the technical and editorial reviews pass.

Keep the roles separate

Keep research, drafting, and review in separate hands. When you gather context, don’t write the final prose. When you author, write from the gathered context, and don’t invent facts. When you review for editorial quality, work from the document alone, without the codebase. The separation keeps each judgment honest.

Don’t encode process metadata

Documentation paths, filenames, and content carry domain and topic names only. Don’t put the documentation framework or the project-management process into them. That rules out wave, phase, and step identifiers, plan and decision-record identifiers, and agent or campaign labels. A reader should see the product, not the process that built it.