Skip to content

41 explainers tell readers to run a script that does not exist in the repo #1125

Open

Description

@yakew7

Where: explainers/*.md (41 of them), a new explainers/code/ folder or similar, scripts/build_explainers.py, tests/.

Current gap: many explainers end their code section with "Run from the repo root (PYTHONPATH=. python3 some-name.py)", but no some-name.py exists anywhere: the code lives only inside the fenced block in the markdown. A reader who tries the command gets "No such file or directory" and has to copy the block out by hand. It is also why nothing can run these blocks in CI (see the open issue about a smoke test), and why a harness change can silently invalidate the numbers quoted next to them.

Repro:

$ grep -l "PYTHONPATH=. python3" explainers/*.md | wc -l
$ ls explainers/code 2>&1

Suggested approach: make the markdown the single source and extract the block to a file at build time (for example explainers/code/<slug>.py, generated like the other derived files and checked by scripts/check_generated_files_current.py), or write the file first and have the build embed it into the page. Then change the sentence to point at the real path (python3 explainers/code/<slug>.py), and keep the printed output block next to the code in the explainer.

Done when: every explainer that tells the reader to run a command points at a file that exists and runs from the repo root, the extraction is checked in CI, and CONTRIBUTING.md says how a new explainer's code is stored.

Activity

  1. added
    documentationImprovements or additions to documentation
    help wantedExtra attention is needed
    on Oct 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationhelp wantedExtra attention is needed

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions