Skip to content

docs.md

Latest commit

 

History

History
162 lines (134 loc) · 8.93 KB

docs.md

File metadata and controls

162 lines (134 loc) · 8.93 KB
Raw

Documentation Guidance

Detailed documentation rules for AGENTS.md.

Contents

Document ownership and ordering

  • README.md owns concise orientation, quickstart, capabilities, and API navigation. Place "Use this crate when" immediately after Introduction.
  • CONTRIBUTING.md owns prerequisite setup, checks, fixes, tests, security, and PR preparation. Dedicated task guides own detailed benchmark, coverage, release, and dependency-maintenance procedures.
  • REFERENCES.md owns bibliographic provenance. Keep the bibliography thematic and preserve citation identifiers and deep links.
  • docs/mathematical_basis.md owns mathematical explanations, assumptions, guarantees, and derivations. Put API selection and geometry scope near the top, before detailed algorithm discussions.
  • Maintain Contents navigation. Sort independent algorithm discussions and unordered capability bullets lexicographically within coherent groups; preserve prerequisite and procedural order.
  • Link between content owners instead of duplicating detail. Keep useful explanations and numerical limitations when moving or shortening material.
  • AGENTS.md is the short entry point for agent rules. Keep detailed Git, testing, and documentation policy in the matching docs/dev/ guide and route tasks there from the Required Reading table.
  • Code organization owns module and file placement. Update its map when ownership or layout changes; keep command procedures in their existing contributor, benchmark, script, and release guides.

Command discovery and placement

Bare just generates the complete public recipe list, including arguments and useful descriptions, directly from Just. Use an explicit private default recipe so lexicographic source sorting cannot change that action. Keep recipe definitions sorted lexicographically; do not maintain a second help list or help alias.

Name recipes by their purpose and preserve equivalent semantics across la-stack, delaunay, causal-triangulations, and markov-chain-monte-carlo: check validates without changing sources, fix applies changes, and ci composes final validation. Tests and security scans belong in contributor guidance. Keep distinct scopes, feature configurations, and workloads, while removing verified duplicate wrappers and updating their callers.

README Quickstart owns useful library usage, bare just, and concrete runnable examples such as just examples or cargo run --locked --example solve_5x5. Link prerequisite setup to CONTRIBUTING. This library has no binary; do not add a run recipe solely for consistency with application repositories.

Discuss individual commands in their owning sections instead of copying the full recipe list. Release and dependency maintenance remain maintainer workflows in their dedicated guides. A shared-package upgrade does not rewrite local recipes or documentation automatically.

Filename conventions

Under docs/, including its subdirectories, name documents by their primary purpose:

Purpose Filename convention Examples
Task guide with commands and instructions for execution Uppercase verb or verb phrase, preferably a gerund RELEASING.md, BENCHMARKING.md, MEASURING_COVERAGE.md, TUNING_PERFORMANCE.md
Discussion of invariants, principles, policy, or architecture Lowercase descriptive name mathematical_basis.md, code_organization.md, dev/testing.md
Reference material, analysis, or results report Lowercase descriptive name roadmap.md, performance.md

A few command examples do not turn a discussion into a task guide. For example, dev/testing.md explains test-design policy; TESTING.md would describe how to execute a testing workflow. Keep conventional directory indexes named README.md. This convention does not change standard filenames at the repository root, such as AGENTS.md, CONTRIBUTING.md, and REFERENCES.md.

Apply the convention to new documents and deliberate documentation renames. MEASURING_COVERAGE.md describes coverage execution, and performance.md reports measured results. Git and GitHub procedures live in dev/MANAGING_CHANGES.md. Reserve TUNING_PERFORMANCE.md for a guide to optimizing code; BENCHMARKING.md owns measurement and comparison workflows. When renaming a document, update links, ownership maps, validation, and any generators or configured output paths together. Preserve historical archive paths; never rename a generated report without updating its source workflow.

README and rustdoc guides

src/lib.rs includes the README with #![doc = include_str!("../README.md")], so README examples are also the docs.rs landing-page examples.

Keep the README quickstart and brief capability descriptions discoverable. Put fuller worked API examples and caller contracts in the documentation-only guide module in src/lib.rs. Preserve numerical limitations and error semantics in the linked guide when shortening a README section.

Links and published destinations

  • Link API references and worked API guides to docs.rs. Keep repository-owned mathematical background, benchmark reports, roadmap, contributing, and release instructions on GitHub, using absolute URLs to the intended revision.
  • README links and Contents anchors must work on both GitHub and generated rustdoc. Repository-relative file links may resolve incorrectly from rustdoc; verify destinations in both contexts.
  • Within Rust docs, use intra-doc links where the referenced item is available under the selected features.
  • Choose docs.rs latest links for intentionally current guidance and explicit versions for release-specific contracts. docs.rs builds published crates; merging changes does not publish new guide pages. Local rendering does not establish availability on the published site.
  • Active repository navigation uses the default branch (main here), while release metadata policy preserves those destinations. Keep measured artifact links, archived reports, historical release records, and citation provenance pinned to their original revisions.

Executable examples

  • When changing Rust examples in README.md, mirror executable versions in the private readme_doctests module in src/lib.rs. Keep mirrors hidden so they do not duplicate the landing page, but runnable by cargo test --doc.
  • README examples requiring optional features may remain rust,ignore for default-feature doctest compatibility. Give them hidden mirrors gated by the matching #[cfg(feature = "...")], and verify the matching feature set, for example cargo test --features exact --doc.
  • Guide examples run directly as doctests. Gate feature-dependent guides with the matching feature; remove obsolete private mirrors when examples move out of README into guides.
  • Run just doc-check for changed guide docs and inspect generated pages and anchors for explicit links, which rustdoc does not validate. Test changed executable examples with the default and matching feature doctest recipes.
  • Ordinary Markdown changes use just markdown-fix and just markdown-ci; the latter includes Markdown and spelling checks.

Scientific notation and references

Unicode mathematics is welcome when it improves readability, including ×, ≤, ≥, ∈, Σ, ², and 2^-50. State invariants mathematically where possible, for example |A[i][i]| > Σ_{j≠i} |A[i][j]|.

Use numbered REFERENCES.md citations such as \[8\] and \[9-10\] in algorithm documentation. Link scientific claims to specific reference sections or entries and describe conditioning behavior. Keep source attribution with the owning explanation when material moves.

Release metadata and generated files

Do not bump package versions during ordinary documentation work. When the maintainer explicitly requests release/version changes, keep README la-stack dependency snippets synchronized with Cargo.toml and follow Releasing. Update documentation before publishing a new crate version: crates.io documentation changes also require a new version.

Never edit CHANGELOG.md directly. just changelog generates, post-processes, archives, and formats the changelog through the pinned shared CLI; just changelog-unreleased <tag> <date> prepends unreleased changes. Commit-message guidance lives in Git and GitHub guidance. Benchmark report and generated asset ownership belongs in Benchmarking.