Skip to main content

readme-standards

Groupsum README Standards

readme-standards

Versioned package README generation, authoring checks, and pytest gates.

pypi: readme-standards Source version: 0.1.0 Python: >=3.11 Layer: developer-tools Lifecycle: active License: Apache-2.0 Notice: attribution

Monthly PyPI downloads: readme-standards README hits: readme-standards

README standards: CI gate Tests: repository CI Certification: not certified Governance: repository policy Evidence: test suite

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:main
  • pytest11 → 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.


More Documentation

See the complete outline, branding contract, tool schema, authoring guide, and implementation guide.

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.


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.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for readme-standards 0.1.0
File Size Uploaded Provenance Actions
readme_standards-0.1.0.tar.gz 106.6 kB Without provenance Details for readme_standards-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for readme-standards 0.1.0
File Interpreter ABI Platform Actions
readme_standards-0.1.0-py3-none-any.whl Python 3 none any Details for readme_standards-0.1.0-py3-none-any.whl

Total release size: 137.9 kB

Release files / readme_standards-0.1.0.tar.gz

Download URL readme_standards-0.1.0.tar.gz
Size 106.6 kB
Tags Source
SHA-256 checksum
How to use checksums
8c58d295fc0ab1384d27d7b56ad0915e2f52c3cbd3f4029dfda9ccda546392a5
BLAKE2b-256 checksum
How to use checksums
149ac473a5e9b70fb5c5427ad5a0c34e3fa778b0f0f8a749cc6cbacb5faa409c
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.0-py3-none-any.whl

Download URL readme_standards-0.1.0-py3-none-any.whl
Size 31.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8b6954f74180c659f7d1c52f84ba909cfde7abf5c5f8bc39f19bffd31441661f
BLAKE2b-256 checksum
How to use checksums
99e9d72ef960813f4b013ac34d39a4410e11dedc19380ef2356fbf12f6b1f984
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.0

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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page