Preview docs locally

The project's documentation is a properdocs site with mkdocstrings for the API reference. One task builds it; another serves it with live reload.

One-shot build

./workflow.cmd document

Runs properdocs build and opens the rendered site/index.html in your default browser. Good for a quick check.

Under WSL the file is handed to Windows instead, since there is no Linux browser to open it with: the path is translated with wslpath -w and passed to cmd.exe. If you still have wslview from the deprecated wslu package installed it is used first, but it is no longer required. Opening is best-effort on WSL only — cmd.exe reports failure even when it worked, so the task prints a message rather than failing if the browser can't be reached. If your distro has Windows interop disabled, ./workflow.cmd document.build still builds the site and you can open site/index.html yourself.

Live reload

./workflow.cmd document.serve

Starts a local server (default http://127.0.0.1:8000) and watches src/ plus docs/ for changes. Edit a docstring or a markdown file and the browser refreshes in place. Press Ctrl-C to stop.

src/ is in the watch list because mkdocstrings reads docstrings directly — changing a Google-format docstring in src/afas_mcp_server/ regenerates the API reference page on the fly.

What the build does

  1. Reads properdocs.yml for site config, nav, and plugins.
  2. The include-markdown plugin pulls README.md into docs/index.md.
  3. The mkdocstrings plugin walks src/ and renders the API reference under docs/reference/api.md.
  4. The rest of docs/ is rendered as plain markdown.

Adding a page

  1. Drop a new .md under docs/<section>/.
  2. Add it to the nav: block in properdocs.yml.
  3. Either rebuild (./workflow.cmd document) or rely on the live-reload server.

Docstring style

mkdocstrings is configured for Google style (docstring_style: google in properdocs.yml). Sections it understands: Args:, Returns:, Raises:, Yields:, Examples:. Other formats render as plain text — useful, but you'll get less typed output and fewer cross-links.

See also