Every Code Block Is a Test: A Free‑Tier Doc Example Gate

说明与用途

通过在 CI 中运行文档中的标记代码块，确保示例可执行，提前捕获错误，减少后续维护成本。

问题

Documentation examples are often never executed, so broken code slips into PRs and only surfaces when users copy it, causing maintenance overhead and delayed fixes.

结果

The gate prevents broken examples from reaching production, reduces triage of user issues, and keeps documentation trustworthy.

工作流

• 1. Mark runnable blocks with a run marker after the language tag in fenced code blocks.
• 2. Add scripts/example_runner.py to the repo.
• 3. Configure CI to execute the runner on PRs that modify documentation files.
• 4. When a PR changes a doc, a model drafts the example, a human verifies the marker and assertions, and CI runs the block against the real toolchain.

证据

The gate needs three pieces: a marker convention, a runner script, and a CI job.

来源

When a PR changes a doc, have a model draft the updated example, a human verify the marker and assertions, and CI execute the block against the real toolchain.

来源