Make the quickstart installable, and split the README into docs/

[alkaz-nodemaven]

Why

An outside developer reading 0.1.3 from PyPI reported that the quickstart imports requests while pip install nodemaven does not provide it. Reproduced 2026-09-10 in a clean venv holding only nodemaven==0.1.3: the first thing anyone copying the README hits is ModuleNotFoundError.

What

nodemaven[requests], an extra and not a dependency. requests is imported nowhere in src/ and stays that way - check.connect() writes its own CONNECT precisely so that no HTTP library is needed to read a status line, and an HTTP library discards the status line, the reason phrase and the headers that are the diagnosis on this gateway.

The near miss worth knowing: an undeclared extra is not an error. pip answers nodemaven[nosuchthing] with a warning and installs without it, so the documented line would have gone on failing while the README looked fixed. A test now reads pyproject.toml and asserts every extra the documentation names is declared.

The README was split. 984 lines, over half reference and measurement, so a reader arriving from PyPI met the API reference before the second example. Now README.md (499 lines) plus docs/api-reference.md, docs/validation.md, docs/observed-behavior.md. Nothing was deleted - the measurements moved at full length, because summarising a measurement turns it into an opinion.

Every outbound link is absolute at blob/main: PyPI resolves nothing relative, so ](docs/validation.md) 404s on the package page.

api.py's module docstring was wrong and shipped that way in 0.1.3. Its "What is still not measured" block claimed the six write endpoints had never been called and the page-number base was unknown. Both were settled 2026-09-09 and the findings sit in the method docstrings of the same file. Corrected in place with the note: a module docstring reads as authoritative and was believed over the code it summarises.

On the tests

A split is the moment a by-name scan silently stops testing anything, and every check in test_readme.py scanned README.md by name. So the corpus is named rather than globbed - a new docs/ file fails the suite until somebody decides what checks it is owed - per-file checks say which file they mean, and every scan asserts it found something first.

Each new test was verified by breaking what it guards, five mutations and five failures: rename the extra, delete the install line, make a link relative, delete a docs/ link, rename a ```python fence to ```py.

Two of those reported MISSED on the first attempt and the mutations were wrong, not the tests - replace(..., 1) against four links and two imports left the originals in place. A mutation that does not fully remove the thing clears a test it never exercised.

The link tests also failed first on ](LICENSE) and ](docs/validation.md) inside the HTML comments explaining that those spellings are forbidden - the test caught the note documenting the rule, not a breach of it. Both now read the comment-stripped prose fixture. The second one was worse and silent: a comment naming docs/validation.md satisfies name in text, so it would have gone on passing after the real link was deleted.

Not a release

No version bump. PyPI still serves 0.1.3 and __version__ here is also 0.1.3, which is recorded under ## Unreleased in the CHANGELOG. The reported bug is not fixed for anyone arriving from PyPI until a release - the long description and the extra both travel with a release and never with a push.

Test plan

• pytest -q - 355 passed, 3 skipped
• Mutation-checked each new test, 5/5 caught
• python -m build + twine check - both artifacts PASSED
• Wheel metadata carries Provides-Extra: requests and Requires-Dist: requests>=2.25; extra == "requests"
• No Cyrillic, no em-dashes in the tree
• ci-ok on five interpreters

---

Summary by cubic

Fixes the quickstart failing with ModuleNotFoundError by making requests an optional extra (nodemaven[requests]) rather than a dependency, and splits the 984-line README into docs/ so PyPI readers see examples before the reference. Also corrects api.py's module docstring, which shipped stale claims in 0.1.3.

• The extra is optional because requests is not imported anywhere in src/; the package writes its own CONNECT.
• The docs split moves reference and measurement content unchanged; outbound links now use absolute blob/main URLs so they work on PyPI.
• test_readme.py now covers docs/ and asserts every documented extra is declared in pyproject.toml.
• No version bump: PyPI still serves 0.1.3, so the quickstart fix only takes effect on release.

^{Written for commit c9261e1. Summary will update on new commits.}

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 1f6c0394-a2ec-4998-ac1c-4af612734c2a

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}