Skip to content

docs: rewrite the README and generate the references in docs/ - #38

Open
botandbang wants to merge 3 commits into
bnb/tsdocfrom
bnb/readme
Open

botandbang wants to merge 3 commits into
bnb/tsdocfrom
bnb/readme

Conversation

@botandbang

Copy link
Copy Markdown
Contributor

Stacked on #35.

The README is now organised for someone landing on it: what docov does and who it's for, install per channel, a quickstart, how coverage is counted and why, task recipes, and pointers to full references. It's about 4,900 words, down from 5,400, and keeps every fact the old one had, here or in docs/.

Added

  • docs/config.md, generated from docov.schema.json: every key with its type, default, values and sub-keys.
  • docs/checks.md, generated from the check registry: each check's module docs, options, and a failing and a passing example with docov's real output.
  • docs/formats.md, generated from the format registry: each format's module docs and a real sample on tests/fixtures/quickstart (version and cobertura timestamp shown as X.Y.Z and TIMESTAMP).
  • docs/cli.md: docov --help.
  • tests/docs.rs and tests/docs/: generate those four pages and run each README console block on a fresh copy of tests/fixtures/quickstart. They fail when a page or example is stale, and DOCOV_BLESS=1 cargo test --test docs rewrites them.
  • tests/fixtures/quickstart and tests/fixtures/checks//{fail,pass}: the README's sample project, and each check's examples, which the test requires to fail and pass.

Changed

  • README.md, rewritten as above. A few claims now match the code: --quiet keeps the lines after the total, badges are blue with a negative threshold too, the examples gate doesn't add the figure to the text report, --stdin-filename also conflicts with --explain, and the data branch's concurrency group belongs in the caller's workflow.
  • src/report/*.rs: module docs only, now holding each format's facts from the old README, since docs/formats.md is built from them.

Removed

  • The README's long Formats, Doc checks and docov.json sections, now in docs/.

@bnb
bnb added this pull request to stack #39 November 9, 2026 06:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant