Documentation development¶
The project homepage stays at /robot-harness/; generated guides live under
/robot-harness/guide/. Both are published together. Markdown in this repository
is the only maintained guide content. mkdocs.yml selects pages and groups the
navigation for users, integrators and contributors; the build copies these files
to an ignored staging directory before rendering with MkDocs Material.
Build and preview¶
Requires Python 3.9+; documentation packages do not affect Core builds:
python3 -m venv build-docs-venv
build-docs-venv/bin/python -m pip install -r tools/docs/requirements.txt
build-docs-venv/bin/python -m unittest discover -s tools/docs -p 'test_*.py'
build-docs-venv/bin/python tools/docs/build.py
python3 -m http.server 8768 --bind 127.0.0.1 --directory build-docs/site
Open http://127.0.0.1:8768/robot-harness/guide/docs/index.html. The prefix matches
GitHub Pages so local navigation and media checks exercise the deployed paths.
Stop the preview server with Ctrl-C. Generated output remains in build-docs/;
never commit the virtual environment, staged Markdown or rendered HTML.
Authoring and links¶
Edit the original Markdown, add new pages to mkdocs.yml, and rebuild. Keep
repository-relative Markdown links: the renderer converts them to site pages.
Links to source files and directories open the matching GitHub revision instead
of publishing a second copy of the code. The footer identifies that revision;
for local uncommitted work it identifies HEAD, so publish only a committed build.
The homepage's Docs link opens the generated reading guide. Its existing asset
and video URLs stay unchanged.
The homepage leads with actual model-guided navigation under shared coordination, followed by a separate real-model waiting-task withdrawal recording. Historical controlled coordination clips retain their own group and scope. It then groups related recordings into compact cards (one column on small screens). The shared coordination group separates navigation, manipulation and waiting-decision withdrawal, with recorded versions and scope in the recording notes. Video players load metadata and posters initially; users choose playback. README keeps one inline model video and links to the grouped demonstrations. Keep each run separately playable; a montage must not imply one continuous run across these scenarios.
The final HTML check rejects broken local pages, media and anchors. External links are not fetched; source availability is checked against the checkout. Search runs in the browser with a generated index. Fonts and theme assets are served with the site; no analytics or remote font service is configured.
CI and publishing¶
The documentation workflow builds and checks pull requests without deployment.
Only a successful build from master can deploy, through the GitHub Pages
environment. Repository Pages must use GitHub Actions as its publishing
source. The workflow uses a read-only build job; Pages write and OIDC permissions
are limited to the deployment job. Failed builds cannot replace the live site.
The separate product homepage remains its own HTML presentation; MkDocs generates the guides, not a duplicate Markdown body to maintain. To change the generator later, preserve the Markdown and public homepage/media paths. Generated API symbol documentation, translated editions and versioned release sites remain later work; the API entry map links current signatures.