openswarm/docs/README.md

docs

A self-contained, local-only documentation generator built with Zensical (the Material for MkDocs team's Rust-based successor to MkDocs). It builds a static site that mirrors the codebase — pages are generated from docstrings, READMEs, and the frontend source on every run, so the docs stay in sync as the code changes. Same "drop-in folder, re-run to refresh" spirit as dependency-graph/.

Use it

./docs/run.sh            # build the site and open it
./docs/run.sh --serve    # live-reloading dev server (great while writing docstrings)

The first run creates an isolated docs/.venv and installs the doc tooling there. Output lands in docs/site/ (git-ignored).

What it pulls in

The site mirrors the repo: every top-level folder becomes a sidebar section, populated by whatever docs live under it.

Source	Becomes (content/…)
Any **/*.py in a real Python package (e.g. backend/)	<folder>/… — one mkdocstrings page per module, in that folder's section.
Every README.md / loose *.md under a folder	<folder>/… — copied verbatim into that folder's section.
Root-level Markdown (README.md, GETTING_STARTED.md, …)	general/ — grouped under a synthetic "General" section.
frontend/src (TSDoc)	frontend/ — TypeDoc reference (best-effort; needs Node + one-time network).

Add a module, a README, or a whole new top-level folder and it appears on the next run — Zensical infers the navigation from the directory tree, so there's no nav to maintain. API pages are only generated where a real package exists (a complete __init__.py chain); non-package folders contribute their Markdown only.

How it differs from a plain Zensical site

Zensical doesn't run MkDocs plugins (no mkdocs-gen-files / mkdocs-literate-nav). So instead of generating pages inside the build, gen_pages.py runs before the build as a plain script and writes real Markdown files into per-folder sections under content/. Generated files are tracked in docs/.gen_manifest and removed precisely on the next run; the hand-written content/index.md and the static assets/, stylesheets/, and javascripts/ folders are left untouched.

Files

file	role
run.sh	bootstraps the venv, runs TypeDoc, generates pages, builds/serves, opens the site.
zensical.toml	site config (theme, markdown extensions, mkdocstrings options).
gen_pages.py	the engine: walks the repo and writes the content/ page tree (pure stdlib).
content/index.md	the one hand-written page (the landing page).
.venv/, site/, content/{reference,guides,frontend}/	generated, git-ignored.

Knobs

• Docstring style: zensical.toml → [project.plugins.mkdocstrings.handlers.python.options] → docstring_style (currently google).
• Skip directories / featured loose docs: SKIP_DIRS and the curated list in gen_pages.py.
• Theme & navigation features: [project.theme] in zensical.toml.
• Markdown extensions: the [project.markdown_extensions.*] tables.

Notes

• The HTTP API reference is no longer baked into this site — Zensical can't run the Swagger plugin yet. Use FastAPI's built-in /docs (Swagger) or /redoc.
• mkdocstrings support in Zensical is preliminary (no cross-references/backlinks yet); the rest renders normally. Track progress at zensical.org/docs/setup/extensions/mkdocstrings.
• The site is a static snapshot — re-run run.sh to refresh.