From 06338d24d71619aef17c3d04cbe1f1de1bd9aede Mon Sep 17 00:00:00 2001 From: jeqcho Date: Mon, 13 Jul 2026 18:16:31 -0700 Subject: [PATCH] docs: enforce public docstring coverage via ruff D1 and backfill Enable Ruff D1 for public API symbols and backfill CLI contracts so missing public docstrings fail the quality gate. Exempt tests and build scripts from the public API check, document contributor expectations, and advertise the 100% gate in the README badge block. Interrogate coverage: 80.0% before, 100.0% after. Co-Authored-By: Claude Fable 5 --- CLAUDE.md | 2 ++ README.md | 4 ++++ docs/contributing.md | 3 +++ pyproject.toml | 7 ++++++- src/worldevals/cli.py | 2 ++ 5 files changed, 17 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 02031c3..3862e39 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -49,6 +49,8 @@ The package is small and self-documenting, so there's no separate `src/` guide. `uv run pytest --cov`. - **Gates (all required, blocking PR checks):** `ruff check .`, `ruff format --check .`, `mypy` (strict), `pytest --cov` at **100% coverage**. +- Every public module, class, and function needs a docstring, enforced by `ruff` D1; + state the contract, don't restate the name. ## Publishing model checkpoints to HuggingFace (any agent session) diff --git a/README.md b/README.md index dc91dc7..1f4a3d5 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,7 @@ If you know [Inspect Evals](https://inspect.aisi.org.uk/evals/), this is that fo [![CI](https://github.com/robocurve/worldevals/actions/workflows/ci.yml/badge.svg)](https://github.com/robocurve/worldevals/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE) [![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/robocurve/worldevals/actions/workflows/ci.yml) +[![Docs coverage](https://img.shields.io/badge/public%20docstrings-100%25-brightgreen)](https://github.com/robocurve/worldevals/actions/workflows/ci.yml) [![Built on Inspect Robots](https://img.shields.io/badge/built%20on-Inspect%20Robots-indigo)](https://github.com/robocurve/inspect-robots) **[Browse the catalog → worldevals.org](https://worldevals.org/)** @@ -104,6 +105,9 @@ Published checkpoints are catalogued in [WorldPolicies](https://github.com/roboc > forget. Day-to-day conventions (PR-only `main`, the required `ci-ok` check, > one-click releases) are documented in [`CLAUDE.md`](CLAUDE.md). +Every public module, class, and function needs a docstring, enforced by `ruff` D1; +state the contract, don't restate the name. + ```bash uv venv && uv pip install -e ".[dev]" # inspect_robots resolved from the v0.3.0 tag uv run pre-commit install diff --git a/docs/contributing.md b/docs/contributing.md index c2252f9..9caf7c8 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -39,4 +39,7 @@ name, well-formed `https://github.com/...` repo URL, ≥1 task key), and CI requ 100% coverage. Keep `task_keys` in sync with the benchmark's actual registered task names. +Every public module, class, and function needs a docstring, enforced by `ruff` D1; +state the contract, don't restate the name. + See the [API reference](api.md) for the `Benchmark` fields. diff --git a/pyproject.toml b/pyproject.toml index 87d0f4c..e6b913a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -72,7 +72,12 @@ target-version = "py310" src = ["src", "tests"] [tool.ruff.lint] -select = ["E", "F", "W", "I", "UP", "B", "C4", "SIM", "RUF"] +select = ["E", "F", "W", "I", "UP", "B", "C4", "SIM", "RUF", "D1"] +ignore = ["D105", "D107"] + +[tool.ruff.lint.per-file-ignores] +"scripts/**" = ["D1"] +"tests/**" = ["D1"] [tool.ruff.lint.isort] known-first-party = ["worldevals"] diff --git a/src/worldevals/cli.py b/src/worldevals/cli.py index d4bbf28..a8494bd 100644 --- a/src/worldevals/cli.py +++ b/src/worldevals/cli.py @@ -9,6 +9,7 @@ def build_parser() -> argparse.ArgumentParser: + """Create the argument parser for the catalog browsing commands.""" parser = argparse.ArgumentParser( prog="worldevals", description="WorldEvals — the Inspect Evals for robotics (a benchmark catalog).", @@ -67,6 +68,7 @@ def _cmd_tasks() -> int: def main(argv: Sequence[str] | None = None) -> int: + """Run the catalog CLI and return its process exit status.""" parser = build_parser() args = parser.parse_args(argv) if args.command == "list":