docs: overhaul README as marketing landing page by b-j-karl · Pull Request #54 · b-j-karl/api-squash

b-j-karl · 2026-04-10T10:23:12Z

Summary

Redesigns the README as a marketing landing page following analysis of httpie, ruff, uv, and typer READMEs
Adds benchmark SVG chart as hero visual above the fold, "The Problem" framing, scannable feature bullets, "Why api-squash?" positioning table, and PyPI badges
Adds drift guard tests (39 tests) that verify the README benchmark table and SVG chart stay in sync with live package data

Changes

README.md — restructured from 13 sections per the overhaul plan:

Centered name + punchy tagline
Badge row (added PyPI version + downloads)
Hero benchmark chart (above the fold)
"The Problem" section leading with the pain point
Scannable feature bullets with bold lead-ins
Installation (pip + uvx)
Quick Start with before/after example
Benchmarks data table
"Why api-squash?" positioning vs alternatives
CLI Reference with new --no-constants and --wrap options
AI Agent Integration
Contributing (brief, links to CONTRIBUTING.md)
License

docs/benchmark-chart.svg — new SVG bar chart comparing raw source tokens vs compressed output across 5 real packages, with dark mode support

tests/test_benchmark_drift.py — 39 tests that re-run api-squash against installed packages and assert the README table and SVG chart values match reality (within 10% tolerance for rounded SVG labels)

Test plan

All 39 benchmark drift guard tests pass
Verify README renders correctly on GitHub (badges, SVG chart, tables)
Verify SVG chart renders in both light and dark mode

🤖 Generated with Claude Code

Restructure README following best practices from httpie, ruff, uv, and typer. Add centered tagline, PyPI badges, problem statement, scannable feature bullets, benchmark bar chart (SVG with dark mode support), "Why api-squash?" comparison table, and AI agent integration section. Abbreviate CLI reference and contributing sections. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Re-runs api-squash against installed packages and asserts the README benchmark table and SVG chart token counts match live results. README values are checked exactly; SVG labels use 10% tolerance for rounding. Also fixes benchmark table values to match current renderer output. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Addresses the highest-impact recommendation from the README overhaul plan — placing a visual immediately after the badge row so visitors grasp the value proposition in under 5 seconds. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Place the benchmark chart after the problem statement so the pain point hooks the reader before the proof arrives. Add a bold "Tokens:" prefix to the SVG legend so the unit of measurement is immediately clear. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Replace em-dashes with periods/colons/parens, vary the feature bullet structure, swap stiff phrasing ("ingest", "compact Markdown", "token-efficient") for plainer language. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

This PR redesigns the project README into a more “landing page” style document (hero visual, positioning, quick start, benchmarks) and adds automated “drift guard” tests intended to keep the published benchmark numbers (README table + SVG chart) aligned with live measurements.

Changes:

Overhauled README.md structure, adding a benchmarks section, a positioning table, and updated CLI docs.
Added docs/benchmark-chart.svg as a hero benchmark visualization (with dark-mode styling).
Added tests/test_benchmark_drift.py to recompute benchmarks against installed packages and assert README/SVG values match within tolerances.

Reviewed changes

Copilot reviewed 2 out of 3 changed files in this pull request and generated 7 comments.

File	Description
README.md	Marketing-style restructure; adds benchmark table and expanded CLI reference/options.
docs/benchmark-chart.svg	New SVG hero chart used by the README to visualize token reductions.
tests/test_benchmark_drift.py	New drift-guard test suite to validate README benchmark table and SVG values against live package measurements.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-10T10:37:10Z

+# Cache benchmarks across tests in this module (expensive to compute).
+_benchmark_cache: dict[str, dict] = {}
+
+
+def _get_benchmarks() -> dict[str, dict]:
+    if not _benchmark_cache:
+        for pkg in PACKAGES:
+            _benchmark_cache[pkg] = _benchmark(pkg)
+    return _benchmark_cache


Running a full benchmark over Django/FastAPI by scanning + parsing every installed .py file is likely to be very slow, especially with the CI matrix (3 OS × 4 Python versions). Consider marking this module as slow and running it in a separate job / on a reduced matrix (or behind an env var), otherwise PRs may time out or become flaky.

Already handled. ci.yml already has a dedicated benchmark job (single Ubuntu runner, Python 3.13) that runs pytest -v -m benchmark, while the main test matrix runs -m 'not benchmark'. The missing piece was the pytestmark = pytest.mark.benchmark on the test module — now added.

Copilot · 2026-04-10T10:37:11Z

+    def test_table_present(self):
+        text = README.read_text(encoding="utf-8")
+        table = _parse_readme_table(text)
+        assert table, "No benchmark table found between markers in README.md"


The assertion message says the table is found “between markers”, but _parse_readme_table doesn’t actually look for the / markers; it triggers off a header substring match. Either update the parser to use the markers (more robust), or adjust the error message to match the current behavior.

Suggested change

assert table, "No benchmark table found between markers in README.md"

assert table, "No benchmark table found in README.md"

Fixed. Updated the assertion message to remove the misleading marker reference.

Resolve conflicts in README.md: keep overhaul structure (hero chart, Why section, --wrap flag) with develop's updated benchmark numbers. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Merge test_benchmark_drift.py and test_benchmarks.py into a single test_readme.py file. Add pytestmark = pytest.mark.benchmark so these tests are excluded from the regular CI matrix and only run in the dedicated benchmark job. Replace RuntimeError with pytest.skip for missing packages so the suite degrades gracefully. Fix misleading assertion message that referenced non-existent markers. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

codecov-commenter · 2026-04-10T11:17:53Z

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

Update stale token counts in benchmark-chart.svg: - requests max_tokens: 2.3k → 2.6k (actual: 2564) - django default_tokens: 256k → 280k (actual: 279987) - django max_tokens: 101k → 125k (actual: 124560) Adjust bar widths proportionally to match new values. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

b-j-karl and others added 5 commits April 10, 2026 21:56

docs: de-AI the README tone

bd478b9

Replace em-dashes with periods/colons/parens, vary the feature bullet structure, swap stiff phrasing ("ingest", "compact Markdown", "token-efficient") for plainer language. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

b-j-karl requested a review from Copilot April 10, 2026 10:32

Copilot started reviewing on behalf of b-j-karl April 10, 2026 10:33 View session

Copilot AI reviewed Apr 10, 2026

View reviewed changes

b-j-karl and others added 2 commits April 10, 2026 22:46

Merge origin/develop into docs/readme-overhaul

3d3c0e3

Resolve conflicts in README.md: keep overhaul structure (hero chart, Why section, --wrap flag) with develop's updated benchmark numbers. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

b-j-karl merged commit 9ff5834 into develop Apr 11, 2026
14 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: overhaul README as marketing landing page#54

docs: overhaul README as marketing landing page#54
b-j-karl merged 8 commits into
developfrom
docs/readme-overhaul

b-j-karl commented Apr 10, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI Apr 10, 2026

Uh oh!

b-j-karl Apr 10, 2026

Uh oh!

Uh oh!

Copilot AI Apr 10, 2026

Uh oh!

b-j-karl Apr 10, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov-commenter commented Apr 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	assert table, "No benchmark table found between markers in README.md"
	assert table, "No benchmark table found in README.md"

Conversation

b-j-karl commented Apr 10, 2026

Summary

Changes

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

b-j-karl Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

b-j-karl Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov-commenter commented Apr 10, 2026

Codecov Report

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants