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

Описание и применение

Гейт, запускающий примеры кода из Markdown, предотвращает попадание испорченных примеров в PR‑ы, снижая количество ошибок пользователей и ускоряя исправления.

Задача

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.

Источник