Skip to content

docs: split README into a short pitch and docs/ pages - #102

Merged
mgiovani merged 3 commits into
mainfrom
docs/readme-pitch
Oct 14, 2026
Merged

mgiovani merged 3 commits into
mainfrom
docs/readme-pitch

Conversation

@mgiovani

Copy link
Copy Markdown
Owner

Summary

The README grew to 721 lines, with every rule, the corpus tables and the full config reference inline. This PR turns it into a 117-line pitch (what stopslop is, install, one real run, why, groups, minimal config, CI, non-goals) and moves the long-form content, verbatim, into docs/:

Page Holds
docs/README.md index
docs/why.md intro, why existing linters miss this, full non-goals
docs/usage.md install variants, usage, git-aware selection, baseline, exit codes
docs/rules.md rule groups, tier counts, the per-rule table
docs/prose.md prose linting
docs/configuration.md config file, path exemptions, user-defined rules, --check-imports
docs/suppression.md suppression directives
docs/benchmarks.md corpus measurements, human splits, candidate tells

These files map one to one onto pages of the docs site in #101.

Other changes

  • --help footer points at docs/README.md.
  • SARIF helpUri points at docs/rules.md. The old README.md#slopNNN fragment never resolved, because the table has no per-code anchors; docs: rule reference site with one page per rule #101 adds real per-rule pages.
  • bench/score_corpus.py (--readme becomes --rules-doc) and bench/corpus/results.py read the rule table from docs/rules.md. It parses 51 rows, matching --list-rules.
  • AGENTS.md: "update the README rule table" becomes docs/rules.md.
  • README links are absolute, so they also work on crates.io.

Verification

  • A normalized-line diff of the old README against the new README plus docs/*.md drops nothing. The 11 changed lines are reflowed text or links that now cross files.
  • Every relative link and anchor in README.md and docs/*.md resolves.
  • just check passes. stopslop README.md docs/ reports zero findings.

Merge-order note: The feat/design-style-layer branch (#86, #87) adds rule rows to the README table. Whichever of the two lands second moves those rows into docs/rules.md.

- README shows findings.png, formats.png and suppress.gif again
- docs/usage.md links rules.md for groups instead of a stale copy missing provenance
- SLOP045 added to the path-gated list
- exit 2 also covers a rule that panicked on a file
- why.md names prose and image metadata, and the opt-in comment-length cap
- "checks" -> "rules" where it meant Rule; no Markdown links inside bash comments
- docs pages link back to the docs index
- CHANGELOG Changed entry for the split, SARIF helpUri and --rules-doc
@mgiovani
mgiovani merged commit 512f29c into main Oct 14, 2026
2 checks passed
@mgiovani
mgiovani deleted the docs/readme-pitch branch October 14, 2026 15:22
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