Skip to content

Maintain the documentation

Run these commands from the repository root. Python is needed to build the documentation, not to build or run RustSys.

Install the site tools

Python 3.10 or newer is supported by the pinned documentation dependencies.

python3 -m venv .work/docs-venv
.work/docs-venv/bin/python -m pip install -r docs/requirements.txt

With uv, the equivalent setup is:

uv venv --python 3.13 .work/docs-venv
uv pip install --python .work/docs-venv/bin/python -r docs/requirements.txt

docs/requirements.in pins the three direct tools; docs/requirements.txt locks their transitive dependencies. Refresh the lock deliberately with uv pip compile docs/requirements.in --output-file docs/requirements.txt.

Build and check

.work/docs-venv/bin/python docs/_tools/check_markdown.py
.work/docs-venv/bin/python -m mkdocs build --strict -f docs/mkdocs.yml
.work/docs-venv/bin/python docs/_tools/check_site.py .work/docs-site

The generated site is .work/docs-site/; it is an ignored build artifact. The source check validates repository-relative Markdown links, including the root README. The strict build rejects broken site links and missing navigation pages. The final check resolves local HTML links, images, scripts, and fragment targets in the built output. It does not contact remote websites.

For a local preview, run the following command and stop it when finished:

.work/docs-venv/bin/python -m mkdocs serve -f docs/mkdocs.yml --dev-addr 127.0.0.1:8000

The preview URL includes /RustSys/, matching the configured GitHub Pages path. A local documentation preview does not start a RustEDA service or change the CLI's daemonless execution model.

Where to edit

Add a task walkthrough in docs/guide/, a lookup page in docs/reference/, or a normative requirement in the existing docs/specs/ tree. Add new primary pages to nav in docs/mkdocs.yml. Link with relative Markdown paths so the same guide works on GitHub and in the site. Preserve existing source paths when reorganizing the navigation.

Run executable examples against the current CLI before changing a workflow. Make example workspaces and output paths explicit. Distinguish a documented command contract from illustrative output, and keep budgets and unsupported semantics visible.

Keep the product introduction in the root README.md, walkthroughs in docs/guide/, command summaries in docs/reference/, and exact behavior in docs/specs/. Benchmark measurements, proof receipts and source pins belong in verification/benchmarks/open-hardware/results/. Shared RustEDA marks and the RustSys animation live in docs/assets/; the brand guide documents their use.

The README, homepage and benchmark page publish no synthesis-only measurement tables. The only published benchmark is the RustEDA whole-flow Ibex result (Ibex RV32 with two real IHP SRAMs on IHP SG13G2 / EZ130 8T, compared with LibreLane); link to the RustEDA benchmarks page instead of copying its values. Describe RustSys's part in that run, not separate synthesis timings.

The benchmark publication marker pairs (open-hardware-benchmark, large-hardware-benchmark, parallel-hardware-scaling and gf180-audit in the README; benchmark-16-core and benchmark-full-matrix in the homepage and benchmark page) have been removed. The report tools that rewrote them, scaling_report.py --root-readme, large_report.py, publish.py --root-readme and the --update-docs option of additional_report.py and refresh_report.py, therefore stop with an error when they reach the documentation update. Do not restore the markers to republish a campaign. The dated archives under verification/benchmarks/open-hardware/results/ keep each campaign's complete receipts. Do not revive a certificate listed in the historical proof invalidation registry.

Publish to GitHub Pages

The docs GitHub Actions workflow builds and validates pull requests and changes to main, then uploads a downloadable site artifact. Successful documentation updates on main deploy automatically to GitHub Pages. Pull requests only build and validate the site.

For a manual deployment, start the workflow on main with Publish to GitHub Pages enabled. Leaving that option disabled builds and validates without deploying. The repository's Pages publishing source is GitHub Actions; the deployment job uses the github-pages environment and scoped Pages/OIDC permissions.

The online documentation is lab-emi.github.io/RustSys. Confirm a successful deployment job and check the live URL after publishing.