Skip to content

docs: the console blocks in 06-serving-and-ops.md are never executed by a test #2

Description

@Shashankss1205

Summary

docs/cookbook/06-serving-and-ops.md contains seven ```console blocks showing real command output, and none of them is executed by any test. tests/test_cookbook_serving.py pairs only ```python blocks with their expected output; console blocks are never run. They have already drifted: line 1254 of the doc shows {"status":"ok","version":"0.1.0",...} while grapharc/__init__.py:12 says __version__ = "0.1.1".

Why this matters

This project's documentation is meant to be evidence, not decoration — tests/test_readme.py and tests/test_cookbook_models.py byte-compare command output against the page so it cannot rot quietly. Trustworthy docs are part of the graph engineering discipline this repo argues for: a page that silently contradicts the tool is worse than no page. These seven blocks are the one place that guarantee currently does not reach.

Where in the code

  • docs/cookbook/06-serving-and-ops.md — the console blocks at roughly lines 1247, 1584, 1645, 1672, 1702 (and the stale version string at 1254)
  • tests/test_cookbook_serving.py — the harness that currently skips them
  • tests/test_cookbook_models.pyread this first; it already does exactly this for 02-models.md and is the pattern to copy

Confirm it:

grep -c 'console' docs/cookbook/06-serving-and-ops.md      # 7
grep -n '"version"' docs/cookbook/06-serving-and-ops.md    # shows 0.1.0
grep -n '__version__' grapharc/__init__.py                 # says 0.1.1

What to change

  1. Read how tests/test_cookbook_models.py marks and executes console blocks (<!-- cookbook shell ... --> / <!-- verified: ... --> markers, _run_console).
  2. Pick the blocks whose output is deterministic and mark them so the harness runs and compares them.
  3. For blocks whose output is genuinely machine-dependent (serve binds a port; models --check probes the host), mark them as varies so they are executed for a zero exit code but not byte-compared.
  4. Correct the stale 0.1.0 to match the real version.

How to verify

uv run pytest tests/test_cookbook_serving.py -q
uv run pytest -q          # nothing else may regress

Then prove the new gate works: change one character of an expected block and confirm the test fails.

Acceptance criteria

  • Every console block in 06-serving-and-ops.md is either byte-compared or explicitly marked as varying
  • The stale version string is corrected
  • Editing an expected block makes the suite fail (the gate is real, not decorative)
  • uv run pytest green, uv run ruff check . clean

Skill level — good first issue

No production code changes at all: you are extending a test harness that already exists and copying a pattern from a sibling file. It is an excellent first contribution because it teaches you the repo's core habit — a claim in the docs must have a test behind it. Comment here if you would like guidance on which blocks to treat as deterministic.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgood first issueGood for newcomershelp wantedExtra attention is needed

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions