Skip to main content

ARX-KW / DOCUMENTATION

Website development

Build, validate, and maintain the Stucco documentation site.

The GitHub Pages site is generated in Rust with Stucco 0.5. Stucco supplies the semantic components, accessible skip link, validated Slate theme, and hashed assets. Site-specific layout and prose styles live in assets/site.css. The site follows the browser's light/dark preference and works without JavaScript.

Build locally

From the repository root, using Rust 1.88 or newer and Python 3.11 or newer:

cargo run --manifest-path site/Cargo.toml --locked -- target/pages/arx-kw --base /arx-kw/
cargo clean --doc
cargo doc --all-features --no-deps
mkdir -p target/pages/arx-kw/doc
cp -R target/doc/. target/pages/arx-kw/doc/
python dev/check-site.py target/pages/arx-kw --base /arx-kw/
python -m http.server 8000 --directory target/pages

Open the project's /arx-kw/ path on your local server. To host the site at the domain root instead, build with --base / and serve that output directory. The explicit base path applies to every page, canonical URL, and Stucco asset. The library's generated API reference retains the existing doc/arx_kw/ path. The previous Criterion report entry points to instructions for running current benchmarks; historical timings are not presented as current release results.

Content sources

OutputSource
Landing pageStucco components in site/src/main.rs
GuideRoot README.md
SecuritySecurity and envelope sections of the root README
ChangelogCHANGELOG.md
Implementation reviewCODE_REVIEW.md
Release guideRELEASE.md
Website developmentThis file
API referencecargo doc --all-features --no-deps

Update these Markdown files rather than editing generated HTML. Rustdoc-hidden example scaffolding is omitted on the website. Heading anchors and the sidebar are generated together. The independent site/Cargo.toml and committed lockfile keep website tooling out of the cryptography library's runtime dependencies. The command writes its own files without deleting other content in the output folder; build into an empty output folder for a deployment.

Validation

cargo fmt --manifest-path site/Cargo.toml --check
cargo clippy --manifest-path site/Cargo.toml --locked -- -D warnings
python dev/check-site.py target/pages/arx-kw --base /arx-kw/

The checker verifies the rendered site's landmarks, headings, navigation, local links and fragments, stylesheets, and project-prefixed asset paths. CI performs this check on the exact Pages artifact, including the API reference.

Deployment

The Pages workflow builds the static site and API documentation, checks links, and uploads the complete artifact. On main, it deploys to the github-pages environment using GitHub's Pages actions. Select GitHub Actions as the Pages source in repository settings. The legacy gh-pages branch is preserved but is no longer the publishing source. CI also builds the site on pull requests, without publishing it. No production preview is created by a local build.