mirror of
https://github.com/openswarm-ai/openswarm.git
synced 2026-09-11 20:27:44 +02:00
71 lines
3.6 KiB
Markdown
71 lines
3.6 KiB
Markdown
# docs
|
|
|
|
A self-contained, local-only documentation generator built with
|
|
[**Zensical**](https://zensical.org/) (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
|
|
|
|
```bash
|
|
./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](https://mkdocstrings.github.io/) 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](https://typedoc.org/) 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](https://zensical.org/docs/setup/extensions/mkdocstrings/).
|
|
- The site is a static snapshot — re-run `run.sh` to refresh.
|