Skip to content

Alan Backend Documentation

This site is built with MkDocs ⧉.

Running locally

Use the alan docs commands (from anywhere in the repo):

  • alan docs serve — serve the whole site with fast incremental live reload (only the file you edit rebuilds). Open http://127.0.0.1:8000 ⧉.
  • alan docs serve <component> — scope to one component (or alan docs serve shared) for the fastest reloads while authoring that component. Cross-component links won't resolve in this mode; use the whole-site command for those.
  • alan docs build — build the full site locally (no live reload).

Add --fast to any of the above to skip the API reference (mkdocstrings) for an even faster reload / preview — API pages are stubbed and diagrams may be stale, so it's for prose/structure work, not a publishable build.

Note

Plain mkdocs serve rebuilds the entire site on every keystroke (the monorepo plugin re-materialises its merge dir each build, defeating --dirty). alan docs serve works around this, so prefer it for local work.

Known limitation: mkdocs-click command pages

Editing a CLI command's Python (a mkdocs-click / click_commands(...) page) is not picked up by live reload — mkdocs-click imports the command module and Python caches it in sys.modules, and command groups are assembled from many modules at import time. Restart the serve to see command changes. (Docstrings/signatures of regular ::: mkdocstrings API pages do reload, since those parse source rather than import it.)

Known limitation: the Docstring Tags index

The aggregate Docstring Tags page is built from macros that read tags collected across the whole codebase, with no per-page source it can be tied to — so live reload doesn't refresh it when you edit a docstring's Tags: section. Restart the serve to regenerate the index.

Adding a component / section

  • Components are auto-discovered — any components/<name>/ with a mkdocs.yml + docs/ appears in the nav automatically (via the *include components/*/mkdocs.yml wildcard). No manual wiring. Per-page order/title come from that component's docs/.nav.yml.
  • Non-component top-level sections (anything not under components/*, e.g. a new cross-cutting group, shared, a tool) still need manual wiring:
  • Add a monorepo !include entry for its mkdocs.yml in backend/mkdocs.yml's nav: (so its docs get merged in).
  • Add/curate its entry in the root backend/docs/.nav.yml (the awesome-nav config that owns the rendered top-level structure).

Commands

  • alan docs serve [component|shared] [--fast] - Live-reloading docs server on http://127.0.0.1:8000 ⧉
  • alan docs build [--fast] - Build the documentation site
  • alan docs --help - Full flag reference