readme-standards
readme-standards
Versioned package README generation, authoring checks, and pytest gates.
Overview · Installation · Quick Start · Usage · API · Contributing · Governance · License
Overview
Summary
README Standards is a Python library, command-line tool, and pytest plugin for consistent package documentation. It compares package READMEs with a versioned heading tree, renders metadata-driven fragments, and reports missing authored content.
Why This Package
Monorepos can have hundreds of READMEs that disagree on structure and contain stale package badges. This tool centralizes the heading contract while keeping explanations and examples with each package.
When to Use
Use it when Python distributions need the same documentation structure, package-specific branding, and a CI gate. It can render badges for additional declared registries; automatic manifest discovery currently supports Python pyproject.toml projects only.
Features
- One package-name H1 and 55 fixed H2–H4 sections.
- CommonMark-aware checks with source locations.
- Deterministic branding, installer commands, entry points, and example inclusion.
- Conservative repair with a diff before an explicit write.
- Pytest collection independent of normal testpaths.
- Built-wheel README and legal-document checks.
- Explicit isolated installed-wheel Python example execution.
Non-Goals
The plugin does not certify the quality or truth of arbitrary prose, award external certification, publish packages, manage Trusted Publishers, or execute examples during ordinary README checks. It does not yet discover Cargo, npm, or container manifests.
Getting Started
Prerequisites
Python 3.11 or later is required. Install the published distribution as a development dependency; Git is needed only for source development. Example execution additionally requires venv and pip plus access to the dependencies of the selected wheel.
Installation
uv
uv add readme-standards
pip
python -m pip install readme-standards
Poetry
poetry add readme-standards
Quick Start
Example
Source: examples/quick_start.py.
from readme_standards import outline
headings = outline("example-package")
assert headings[0]["title"] == "example-package"
assert headings[1]["title"] == "Overview"
print(f"{headings[0]['title']}: {len(headings)} required headings")
Expected Result
The example prints example-package: 56 required headings. Its assertions confirm that the package name is the H1 and Overview is the first fixed section.
Usage
Common Workflows
Source: examples/usage.py.
from readme_standards.document import parse
headings, separators = parse("# example-package\n\n---\n\n## Overview\n")
assert [h.title for h in headings] == ["example-package", "Overview"]
assert len(separators) == 1
print("Parsed package title, Overview, and one group separator.")
Configuration
Declare [tool.readme_standards] in each package manifest. The complete machine-readable contract is schema.json; the repository pyproject.toml is a complete working configuration. Brand catalogs may be shared above package directories.
Error Handling
Check failures identify a file, line, rule ID, and corrective action. CLI exit code 1 means policy violations; 2 means configuration or command errors. Repair refuses unknown or duplicate headings, malformed regions, and ambiguous preambles. Read-only checks never repair files.
Best Practices
Keep authored explanations in README.md and runnable examples in maintained source files. Run render after metadata changes, review the diff, and gate both source and built artifacts. Pin the plugin revision in downstream dependency locks and review prose separately from structural checks.
Package Boundary
What It Owns
This package owns the package-guide-v1 outline, its configuration schema, managed fragment generation, diagnostics, and pytest adapter. Package authors own behavioral claims and prose; repository maintainers own shared branding and governance declarations.
Public API and Import Surfaces
The stable top-level exports are POLICY_VERSION and outline(package_name). CLI behavior and the versioned policy are public contracts. Modules such as document, check, and render expose implementation helpers that may evolve before 1.0; consumers should prefer the CLI or pytest integration.
Entry Points
console_scripts→readme-standards→readme_standards.cli:mainpytest11→readme_standards→readme_standards.pytest_plugin
Injected Dependencies
The checker reads an explicit package root, manifest, README, brand catalog, example files, and legal documents. It uses markdown-it-py for parsing, jsonschema for configuration, packaging for names, and pytest for test integration. It imports no target-package runtime code during ordinary checks.
Protocol Consumers
Pytest loads the plugin through its pytest11 entry point. CI and developer tools consume the CLI text diagnostics or JSON report. Downstream repositories consume the packaged schema and versioned outline.
Extensions
Version 0.1 provides no third-party policy or manifest-adapter hook. Propose new ecosystem adapters and policy versions through reviewed contributions. All package-guide-v1 heading labels remain fixed.
Operations and Readiness
Operational Requirements
Ordinary checks run locally without credentials or network access after dependencies are installed. Render and repair write only when --write is passed. Installed-wheel example execution is an explicit command and may install dependencies from configured indexes.
Health and Observability
This is a command-line library, not a long-running service, so it exposes no health endpoint. Use process exit status, pytest results, and check --format json diagnostics to observe policy compliance.
Security and Resource Limits
Run example execution only on trusted projects and wheels. A fresh venv and isolated Python imports are not an operating-system sandbox. Scripts have timeouts; package-local paths cannot escape the package directory. Ordinary checks do not fetch badge URLs or execute examples. See SECURITY.md.
Compatibility
The distribution requires Python >=3.11 and pytest >=8,<10. CI exercises Python 3.11 through 3.14 on Linux and Python 3.13 on Windows. Current discovery requires static PEP 621 name, version, README reference, and SPDX license metadata; dynamic versions need a future adapter.
Verification
Tests
Run uv run pytest --readme-standards. The suite checks every missing section, heading order and parents, authored omissions, safe repair, package-scoped badges, wheel metadata, and actual pytest subprocess integration. tests/test_examples.py executes both maintained examples.
Certification Status
This project has no external certification. A passing README gate establishes the declared structural and mechanical checks only; it does not certify prose completeness, security, or runtime behavior of downstream packages.
Evidence
The CI workflow runs tests, the source README gate, wheel checks, and installed-wheel examples. Its result applies to the tested commit. Positive configured status labels require a local evidence record matching package, version, policy, and checks; authors remain responsible for the record’s truth.
FAQ
Why
Why keep an inapplicable section? Stable locations help readers compare packages. Explain the absence concretely, such as declaring that no CLI entry points are registered, instead of removing the section or writing a bare applicability abbreviation.
How
How is prose protected? Only marked generated regions are replaced by render. Repair moves known sections with their bodies and stops when unknown headings or duplicates make ownership ambiguous. Authored paragraphs remain in README.md.
When
When does a missing section fail? Check and pytest fail immediately. Explicit repair can insert its heading and an authoring comment, but the content gate keeps failing until an explanation is written.
Documentation and Related Packages
More Documentation
See the complete outline, branding contract, tool schema, authoring guide, and implementation guide.
Related Packages
Pytest supplies collection and reporting; markdown-it-py supplies the CommonMark syntax tree; jsonschema validates configuration. This project complements project-specific documentation and example tests rather than replacing them.
Project Links
Contributing
How to Contribute
Follow CONTRIBUTING.md. Include the failing README scenario, a focused change, and regression tests. Preserve authored content and avoid weakening a gate merely to accept a broken document.
Development Setup
Clone the repository, run uv sync --group dev, then uv run pytest --readme-standards. Use uv run ruff check . and uv run ruff format --check . for lint and formatting. Build with uv build.
Notes for Maintainers
Keep schema, policy, renderer, tests, and docs synchronized. Run render when example formatting or package metadata changes. A changed heading contract needs a new policy identifier. Release through the tag-scoped Trusted Publishing workflow documented in docs/release.md; verify artifacts and a clean install after each publication.
Governance
Ownership and Decision Making
Groupsum maintains the project. Submit proposals through issues and pull requests; maintainers decide compatibility, policy changes, and releases. The governing record is GOVERNANCE.md.
Standards and Policies
Package-guide-v1 requires the same heading labels, levels, parents, separators, and order in every package. H1 alone varies with the manifest name. CI checks the plugin’s own README and shipped schema. Content review remains required for package-specific claims.
Lifecycle and Migration
Version 0.1 is active initial development. Existing repositories should audit first, map ambiguous headings manually, preview repair, fill authored gaps, and enable CI before adoption. This work does not migrate or republish downstream packages automatically.
License and Attribution
License
Licensed under Apache-2.0. See LICENSE.
Notices
See NOTICE for attribution.
Metadata
Release files for readme-standards 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| readme_standards-0.1.1.tar.gz | 107.2 kB | Without provenance | Details for readme_standards-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| readme_standards-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for readme_standards-0.1.1-py3-none-any.whl |
Total release size: 138.7 kB
Release files / readme_standards-0.1.1.tar.gz
| Download URL | readme_standards-0.1.1.tar.gz |
|---|---|
| Size | 107.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
999aa59f1a05b1907482330dd4dfb3fccc1b9d6043ce66464e0cdb65e09f8e51
|
|
BLAKE2b-256 checksum How to use checksums |
0ddcb4b129d69751cdce37216ead0b19d4096f3bf1520d179b5bf3f80194bcdd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / readme_standards-0.1.1-py3-none-any.whl
| Download URL | readme_standards-0.1.1-py3-none-any.whl |
|---|---|
| Size | 31.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c7ecb960a5a7587bbbd0a81840bcb86ffff11f6930da1cdf2c0876a9f294327d
|
|
BLAKE2b-256 checksum How to use checksums |
41a3a8670b94531f6ffd246c370928b9018bed59822e308a8cb95786f56bd416
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for readme-standards 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.