Skip to content
RustUse

Contributing

Contributing

Curated docs and generated rustdocs move together.

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

RustUse docs combine curated content under src/content/docs/ with generated API docs 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 Rust API docs live in public/api/ and are treated as build output.
  • Rustdoc source definitions live in docs/rustdoc-sources.json.

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 a sibling use-math checkout at ../use-math. That checkout is 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 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”
  • src/data/crates.ts is the single source of truth for public crate cards, statuses, and docs links.
  • docs/rustdoc-sources.json controls which crate workspaces produce hosted rustdocs.
  • scripts/build-rustdocs.mjs builds workspace rustdocs and publishes stable entry roots under /api/.

Publication dry-run

Section titled “Publication dry-run”
  • Prewire the future crates.io and docs.rs URLs in src/data/crates.ts while a crate is still scaffolded.
  • Keep status: 'scaffolded' until the live registry pages resolve and the crate metadata is ready to point at RustUse.
  • Flip the crate to published only after the RustUse API route, crates.io page, and docs.rs page all match the release state.

Common commands

Section titled “Common commands”
Terminal window
npm install
npm run dev:doctor
npm run dev
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.

If ../use-math is absent, npm run dev still works; it will 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 API 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.

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 limited to use-math, use-geometry, and the current use-combinatorics track until product scope changes.
  • Do not add additional planned crates to navigation, homepage copy, or public set pages early.
  • Prefer linking to generated RustUse API docs 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 entry in src/data/crates.ts.
  • Add or update the curated docs page under src/content/docs/.
  • Extend docs/rustdoc-sources.json if the new crate needs a stable /api/<crate-name>/ entry root.
  • Prewire any future crates.io and docs.rs URLs, but leave them non-live until the crate status actually changes to published.
  • Run npm run build and verify the stable API route resolves 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 API 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.