How-to guides a reader can paste, with the checks off the page

[tony]

Summary

• Add a docs/howto/ section: fifteen task-shaped guides whose visible code is plain Python a reader copies into a file and runs — no >>> prompts, no assertions, no test markers.
• Add a pytest plugin that runs each page's blocks in document order in one shared namespace, so block 2 sees what block 1 bound, which is what a reader pasting in sequence gets.
• Pair every page with a sidecar module holding the hidden checks. A missing sidecar, a missing check, or a check with no block is a hard failure rather than a skip.
• Isolate each page in a private TMUX_TMPDIR and HOME from the runner rather than from page setup, so an example cannot reach the tmux of whoever runs the suite.
• Guard the contract with three test modules covering the page/sidecar wiring, the rendered HTML, and — by running pages against a deliberately broken libtmux — that the hidden checks can actually fail.
• Fail the docs build on warnings, so a broken cross-reference or a page in no toctree stops the build instead of scrolling past.

Prose pages under docs/ are doctests, which are testable but not copyable — a reader cannot paste >>> server.new_session() into a script. A how-to guide needs the opposite, and the doctest collector only claims a fence containing >>>, so a bare ```python block would ship untested with no warning and no failure.

Changes by area

The harness

• tests/docs/howto_harness.py: parses a page with MyST's own parser, collects its ```python fences in document order, runs them in one namespace, and calls the sidecar's check_N(ctx) after block N. Its pytest_collect_file wrapper replaces the aggregated collector list for how-to pages so the doctest plugin does not also claim them.
• The parser reads myst_enable_extensions from docs/conf.py rather than restating it. Whether a run of backticks becomes a fence depends on the enabled extension set, so a copy would drift the first time the site's config changed — and drift means a block that renders on the page but never runs.
• ctx.run_block(n, namespace={}) re-runs a block in a fresh world, which is how a page showing if server.is_alive(): gets both branches checked from one visible block.

The guides

Fifteen pages, grouped in the index by what you are driving:

Group	Pages
Servers	start a server, run multiple servers, connect to an existing server, check if tmux is running
Lookups	connect to an existing session, window, pane
Self-location	detect you are inside tmux; find the session, window, pane you're in
Panes	send keys, send keys to every pane, create panes, create a floating pane

The guards

• tests/docs/test_howto_harness.py: the tree is non-empty, every page's contract resolves, every page the run was pointed at produced an item, each page opens with the anchor its filename implies, and each appears in the toctree beside it.
• tests/docs/test_howto_rendering.py: rejects assertions, pytest imports, harness names and prompts in a visible block; rejects any line the sphinx-copybutton prompt pattern matches, read from docs/conf.py; and allows only python and console as rendered languages.
• tests/docs/test_howto_mutations.py: re-runs each page that types a command and reads the answer back against a libtmux whose send_keys never presses Enter, and requires the page's own checks to fail.

Conventions and build

• docs/AGENTS.md: carves out docs/howto/ from the doctest rules that govern the rest of docs/, and states what visible code owes a reader who runs it verbatim.
• docs/justfile: passes -W to sphinx-build.

Design decisions

The page carries no test scaffolding at all. The pages are the product; an assertion in the block is an assertion in the reader's paste. Everything that makes a page testable lives in tests/docs/howto/<slug>.py, named after the page.

Blocks share one namespace, which inverts the rule for the rest of docs/. Topic pages give every block a fresh namespace and a fresh server, because each is an independent illustration. A how-to page is one script broken into steps, so its second block must see the first block's names.

Isolation belongs to the runner, not the page. A private TMUX_TMPDIR and HOME are set before the sidecar is called, and only sockets under that directory are killed, only while the environment still points at it. A sidecar that had to ask for isolation is a sidecar that can forget.

A mutation probe, because a passing check is not evidence.capture_pane returns the command tmux echoed onto the pane, so a containment test for the answer is satisfied when the keystrokes land — before any shell runs, and equally if none ever will. Without a probe the page reports green while teaching a technique that does not work.

Visible code polls to a deadline and compares whole lines. A fixed sleep is either dead time or a false negative, and a substring test is true before the shell has run. The pages teach the correct shape because a reader runs them verbatim.

Verification

No page carries a doctest prompt — expect no matches:

$ rg '^>>> ' docs/howto/

No page carries an assertion — expect no matches:

$ rg '^\s*assert ' docs/howto/

No colon fence, which renders copy-pasteable but executes nothing — expect no matches:

$ rg '^:::python' docs/howto/

Every guide has a sidecar — both counts are fifteen:

$ fd -e md . docs/howto | rg -v 'index.md'| wc -l

$ fd -e py . tests/docs/howto | rg -v '__init__'| wc -l

Test plan

• uv run pytest --reruns 0 — full suite green
• uv run ruff check . and uv run ruff format --check . — clean
• uv run mypy src tests — clean
• just build-docs — builds under -W with no warning and no broken cross-reference
• test_howto_mutations — every page that reads output back fails when send_keys stops pressing Enter, proving the hidden checks are load-bearing
• test_howto_harness — a page with no sidecar, a missing check_N, and an orphan check_N each fail rather than skip
• test_rendered_blocks_match_the_page_source — Sphinx renders each page's python blocks exactly as written
• Pages pass under pytest -n auto, matching CI's distribution

[codecov]

Codecov Report

❌ Patch coverage is 93.48739% with 31 lines in your changes missing coverage. Please review.
✅ Project coverage is 57.31%. Comparing base (729e5c3) to head (91c7f37).

Files with missing lines	Patch %	Lines
tests/docs/howto_harness.py	81.97%	21 Missing and 10 partials ⚠️

Additional details and impacted files

@@ Coverage Diff @@## master #736 +/- ##
==========================================
+ Coverage 52.37% 57.31% +4.94% 
==========================================
Files 26 42 +16 Lines 3729 4203 +474 Branches 747 778 +31 ==========================================
+ Hits 1953 2409 +456 - Misses 1472 1482 +10 - Partials 304 312 +8 

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.