Skip to content
RustUse

Contributing

Contributing

Curated docs and generated rustdocs move together.

RustUse keeps human-authored guides, crate metadata, and generated RustDocs aligned. The goal is simple maintenance, stable RustDocs paths, and a narrow public surface until support expands deliberately.

Ferris contributing to RustUse Ferris contributing to RustUse

RustUse docs combine curated content under src/content/docs/ with generated RustDocs under public/api/.

The shared RustUse contribution policy lives in RustUse/.github CONTRIBUTING.md. This page covers the docs-repo-specific workflow, tooling, and release expectations.

Scope

Section titled “Scope”
  • Human-authored docs live in src/content/docs/.
  • Generated RustDocs live in public/api/ and are treated as build output.
  • Rustdoc source definitions are generated into docs/rustdoc-sources.json.
  • RustUse root, full, and per-set LLM context files under public/ are generated from sibling use-* workspaces.

Keep curated docs and generated Rustdocs separate. Do not copy generated Rustdoc HTML into src/content/docs/.

Prerequisites

Section titled “Prerequisites”
  • Node.js >=22.12.0
  • npm
  • Rust stable toolchain

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

For faster Rustdoc iteration, you can keep sibling checkouts for configured Rustdoc workspaces, currently ../use-geometry and ../use-math. Those checkouts are optional.

If ../use-math is missing, npm run build:api, npm run build, and npm run dev fall back to cloning the configured GitHub repository from the generated docs/rustdoc-sources.json.

The first cold Rustdoc build can take several minutes because it may need to clone the source workspace and run cargo doc from scratch.

Working areas

Section titled “Working areas”
  • rustuse/Cargo.toml features.full controls the public set inventory.
  • Set workspace Cargo metadata controls crate names, descriptions, keywords, and categories.
  • Live crates.io package records control displayed versions and external package links.
  • scripts/generate-catalog.mjs generates crate catalog data, overview pages, and docs/rustdoc-sources.json.
  • scripts/generate-llms-txt.mjs renders the generated RustUse root, full, and per-set LLM context files in public/.
  • scripts/build-rustdocs.mjs consumes generated Rustdoc sources and publishes stable entry roots under /api/.

Publication dry-run

Section titled “Publication dry-run”
  • Keep crate manifest metadata aligned before publishing so crates.io records resolve with the matching RustUse repository URL.
  • The generated catalog expects every listed crate to have a live crates.io package record with the matching RustUse repository URL.
  • Each supported set is added to generated RustDocs inputs automatically by npm run generate:catalog.

Common commands

Section titled “Common commands”
Terminal window
npm install
npm run dev:doctor
npm run dev
npm run generate:llms
npm run build:api
npm run smoke:dist
npm run smoke:preview
npm run verify:changed
npm run verify:fast
npm run check
npm run validate
npm run validate:full
npm run build
npm run preview

Use npm run dev for day-to-day site work. Use npm run dev:doctor after cloning or when local setup seems off.

npm run dev reuses existing generated API output in public/api/. If that output is missing, it runs npm run build:api once before starting Astro.

Use npm run dev:fresh after changing Rust source workspaces, Rustdoc CSS, or docs/rustdoc-sources.json.

If a configured sibling workspace is absent, fresh Rustdoc builds clone the configured source workspace automatically before generating public/api/.

Use npm run smoke:dist after npm run build when you want to verify the final published artifact shape without rerunning the whole repo validation chain.

Use npm run smoke:preview when you want an HTTP-level check of the served docs and RustDocs routes; it starts and stops its own temporary preview server by default.

Use npm run verify:changed for the fastest changed-files-only lint and formatting loop, and npm run verify:fast when you also want astro check.

Use npm run validate before opening a PR when you want the quickest whole-repo health check, and npm run validate:full when you also want a fresh production build plus the built-route smoke check.

npm install runs prepare, which configures Git to use .githooks/ for this repository. The pre-commit hook runs npm run precommit:check, which applies the changed-file verification path to staged authored files only. If you need to restore that Git config manually, run npm run setup:hooks.

This repository does not ship a project database, shared DB container flow, .env bootstrap, or Ollama setup. Keep contributor setup focused on the docs site, the Rust toolchain, and the configured Rustdoc source workspace.

LLM context maintenance

Section titled “LLM context maintenance”

public/llms.txt is the compact root routing map. It includes primary links, workspace Rustdoc URL patterns, and generated RustUse facades only. public/llms-full.txt carries the expanded root context with generated facades and crates. Per-facade files are generated at both public/{facade}/llms*.txt and public/facades/{facade}/llms*.txt, with both routes serving the same generated content as the canonical short routes.

Run npm run generate:llms after adding, removing, or renaming a sibling RustUse facade or crate workspace. CI runs npm run check:llms and fails when the generated LLM context files are stale. Use llms-full.txt when crate-level context is needed from the root.

Styling layout

Section titled “Styling layout”
  • src/styles/rustuse.css stays as the single Astro entry stylesheet.
  • Shared site styling is split by responsibility under src/styles/rustuse/ into tokens, base, components, and utilities.
  • src/styles/rustdoc-extend.css is the supported place to restyle generated rustdoc pages.
  • src/styles/rustdoc-shell.css styles the generated /api/ redirect pages and workspace index shells.
  • Treat public/api/workspaces/*/static.files/ as generated vendor output. Do not hand-edit hashed rustdoc assets there.

Scope guardrails

Section titled “Scope guardrails”
  • Keep the public support surface aligned with the generated catalog entries rather than ad hoc links or hand-maintained sidebars.
  • Do not add planned crates from other facades to navigation, homepage copy, or public facade pages early.
  • When a local crate name conflicts with an existing published package identity, resolve it in Cargo package metadata before relying on generated docs routes.
  • Prefer linking to generated RustUse RustDocs rather than rewriting rustdoc HTML or scraping docs.rs.

When a new crate becomes supported

Section titled “When a new crate becomes supported”
  • Add or update the crate in the owning set workspace.
  • Add or update the curated docs page under src/content/docs/.
  • Publish the crate when it is ready and verify its crates.io repository URL matches the owning RustUse repository.
  • Run npm run generate:catalog and npm run generate:llms, then npm run build, and verify the generated catalog, root and full LLM files, and stable RustDocs route resolve without a 404.

Pull requests

Section titled “Pull requests”

Keep pull requests focused. A good PR includes:

  • a short summary of the user-visible change
  • the commands you ran locally, ideally including npm run verify:fast, npm run validate, or npm run validate:full
  • screenshots when the change affects layout, navigation, or visual styling
  • notes on any known follow-up work or tradeoffs

The public maintenance path for this repository is PR-only. Plan on one maintainer approval plus passing required checks before anything merges to main. See GOVERNANCE.md and MAINTAINERS.md for the current repo policy and maintainer roster.

Release automation derives version bumps and changelog entries from Conventional Commits. When opening a PR, prefer a title or eventual squash-merge commit title like feat: add crate overview, fix: correct RustDocs route, or docs: clarify onboarding.

Use ! for breaking changes when the public docs contract or release behavior changes incompatibly.

VS Code users can run the matching tasks and launch profiles in .vscode/ instead of typing the commands by hand, but those editor actions should still map back to the npm scripts above.

Releases

Section titled “Releases”

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

Release authority for this repository is defined in GOVERNANCE.md and MAINTAINERS.md.

Release operators should:

  • review and merge the open Release Please PR when the changelog and version bump look correct
  • keep squash-merge titles or direct commit messages in Conventional Commit form so release automation can classify the change correctly
  • keep the repository or organization setting enabled so GitHub Actions can create pull requests with GITHUB_TOKEN
  • treat .github/workflows/deploy.yml as the normal GitHub Pages deploy path for production docs after reviewed changes land on main
  • use the manual dispatch inputs in .github/workflows/deploy.yml when you need to redeploy a specific branch, tag, or commit
  • confirm the generated GitHub release includes the expected autogenerated notes and attached dist/ tarball

Ground rules

Section titled “Ground rules”
  • Preserve the current Starlight and content structure unless the change requires a new pattern.
  • Prefer small, reviewable changes over broad refactors.
  • Do not commit generated dist/ output.
  • Treat accessibility regressions and broken docs routes as release blockers.