Skip to content

Contributing to documentation

Sim2Bot uses Material for MkDocs. Narrative guides are Markdown; Python API pages are generated with mkdocstrings-python and mkdocs-gen-files from the actual SDK source.

Preview locally

cd docs-site
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
mkdocs serve

Open http://127.0.0.1:8000/sim2bot/. The local Sim2Bot development app also uses this URL by default in its Documentation window.

Run the strict build

cd docs-site
python scripts/check_examples.py
mkdocs build --strict

Strict mode treats broken links, missing navigation pages, and other warnings as failures. The example checker compiles every Python block in narrative Markdown and every curated generated-API example. GitHub CI runs both checks on staging, pull requests, and main before the separate publication workflow can deploy docs.

How Python API pages are generated

scripts/gen_ref_pages.py declares the public pages and their stability labels. For each entry it writes a virtual Markdown page containing an mkdocstrings directive. MkDocs then imports the SDK from services/bridge/sim2bot and renders its signature, annotations, docstring, and source.

When changing a public Python method:

  1. Update the implementation and type annotations.
  2. Document every parameter, including its units, accepted shapes or ranges, default, and how combinations of optional arguments change behavior.
  3. Document the return value explicitly, including None for command methods, plus every exception callers are expected to handle.
  4. Add or update the public entry in scripts/gen_ref_pages.py if necessary.
  5. Add at least two practical examples in scripts/api_content.py; include alternate call forms when the API accepts several useful argument combinations.
  6. Run Python tests and the strict docs build.

Generated reference pages intentionally follow this order: callable signature, description, Parameters/Returns/Raises, practical examples, then tips, warnings, and common errors. Horizontal rules separate these groups. Keep units beside the parameter, return value, or attribute they describe; do not repeat ordinary metadata such as Stable, category, or scope in a separate summary card. Only Preview and Experimental lifecycle states receive a prominent notice.

Keep the generated class, method, function, and attribute symbols enabled. Their small colored markers make object kinds scannable in headings and the page table of contents without introducing another metadata section.

Do not hand-edit reference/api/*.md; those pages exist only during the build.

Writing for three audiences

  • Potential users: concise purpose and limitations on the home page and README.
  • New users: outcome-driven tutorials with one clear path and copy-ready examples.
  • Experienced users: complete, searchable API pages generated from source.

Keep tutorials concise and progressive. Put exhaustive parameter detail in the reference so first-time users are not forced through every edge case.