RustUse documentation and generated API reference
Human docs live in src/content/docs/. Generated Rust API docs live in public/api/.

Repository · Docs model · Local development · Generated API docs · Deployment · Troubleshooting

This repository contains the RustUse docs site for rustuse.org. It combines human-authored documentation under src/content/docs/ with generated Rust API docs under public/api/, then publishes the static result to GitHub Pages.

RustUse Docs is the public docs site, not the source workspace for every Rust crate. It has four primary responsibilities:

RustUse separates authored documentation from generated API output on purpose.

Build path at a glance:

rustuse features + set workspaces -> scripts/sync-crate-surface.mjs -> generated catalog and Rustdoc inputs -> scripts/build-rustdocs.mjs -> public/api/ -> RustUse docs site -> rustuse.org

Sibling use-* workspaces -> scripts/generate-llms-txt.mjs -> root, full, and per-set LLM text files in public/ -> rustuse.org/llms.txt

.
├── docs/
│   └── rustdoc-sources.json
├── public/
│   ├── CNAME
│   ├── llms.txt
│   ├── llms-full.txt
│   └── api/
├── scripts/
│   ├── build-rustdocs.mjs
│   ├── generate-llms-txt.mjs
│   └── sync-crate-surface.mjs
├── src/
│   ├── content/docs/
│   ├── data/catalog.generated.js
│   ├── data/catalog.js
│   ├── data/crates.ts
│   └── styles/
├── astro.config.mjs
├── package.json
└── tsconfig.json

Use these prerequisites when working on the site locally:

Node.js >=22.12.0
npm
Rust stable toolchain

If you use nvm or a compatible tool, the repository pins 22.12.0 in .nvmrc.

Run commands from the repository root.

Fastest path to a working local site:

npm install
npm run dev:doctor
npm run dev

If you want to refresh only generated API docs before restarting the site:

npm run build:api

If you already have a fresh build and want to sanity-check the final published artifact shape without rerunning the whole validation chain:

npm run smoke:dist

If you want to verify the served HTTP responses as well, run the preview smoke check directly:

npm run smoke:preview

By default the script starts and stops its own temporary preview server on a free local port. If you want to target an already-running preview instead, set RUSTUSE_PREVIEW_URL first.

The workspace now includes task and launch entries for the core docs workflows:

Use the launch profiles when you want a one-click server start, and use the tasks when you want repeatable terminal workflows from the command palette.

The Rustdoc build pipeline consumes docs/rustdoc-sources.json. That file is generated by npm run sync:crate-surface from the rustuse facade features.full list, set workspace Cargo metadata, and live crates.io package records.

Do not hand-edit docs/rustdoc-sources.json. A set workspace is included automatically when every publishable public package in that set resolves on crates.io with the matching RustUse repository URL.

For faster local iteration, keep sibling checkouts for the configured Rustdoc workspaces. When a checkout is unavailable, scripts/build-rustdocs.mjs falls back to cloning the generated repo URL automatically. That fallback is what CI uses today, so contributors do not need sibling checkouts just to build the docs site successfully.

Generated output currently lands at:

The supported crate entry roots redirect into the workspace bundle so the generated Rustdoc asset layout stays intact.

The public crate catalog is generated into src/data/catalog.generated.js and exposed through src/data/catalog.js and src/data/crates.ts.

Keep the source inputs aligned with:

The public LLM context is split by detail level:

• public/llms.txt is the compact root routing map. It includes primary links, workspace Rustdoc patterns, and generated RustUse facades only.
• public/llms-full.txt is the expanded root context. It includes the same shared sections plus generated RustUse facades and generated RustUse crates.
• public/{facade}/llms.txt and public/{facade}/llms-full.txt are generated canonical per-facade files.
• public/facades/{facade}/llms.txt and public/facades/{facade}/llms-full.txt are generated with the exact same content as the canonical short facade routes.

The generator preserves these marked regions in the generated files:

<!-- BEGIN GENERATED RUSTUSE FACADES -->
<!-- END GENERATED RUSTUSE FACADES -->

<!-- BEGIN GENERATED RUSTUSE CRATES -->
<!-- END GENERATED RUSTUSE CRATES -->

Run npm run generate:llms after adding, removing, or renaming a sibling RustUse facade or crate workspace. The generator scans sibling use-* directories with root Cargo.toml files, prefers Cargo metadata for package names, and renders every expected LLM context file.

CI runs npm run check:llms and fails when any committed LLM context file is stale. The root llms.txt intentionally omits the generated crate block; use llms-full.txt when crate-level context is needed.

The site is intended to deploy to GitHub Pages.

Deployment flow:

Push to main or manual redeploy workflow
  -> build configured Rustdocs into public/api/
  -> build the docs site into dist/
  -> upload the Pages artifact from dist/
  -> deploy static output to GitHub Pages

The primary production deploy path lives in .github/workflows/deploy.yml and runs on reviewed pushes to main. The same workflow also remains available as a manual redeploy path when you need to deploy a specific ref from the Actions tab.

GitHub releases are now created through .github/workflows/release-please.yml.

Release flow:

Merge conventional commits to main
  -> Release Please updates or opens a release PR
  -> maintainer reviews and merges the release PR
  -> Release Please creates the GitHub release and tag
  -> workflow validates the released commit and uploads a dist/ tarball

Release Please is bootstrapped from the repository's current public baseline commit so it does not backfill older history into the automated changelog.

Contributor-facing project docs are already in place:

Use the shared RustUse contribution policy together with the docs contributor guide and this README when onboarding new contributors or maintainers.

Public changes are intended to land through pull requests with passing checks and one maintainer approval before merge.

RustUse Docs is dual-licensed under MIT or Apache-2.0.

• LICENSE-MIT
• LICENSE-APACHE