Skip to content

Add a lint check that every explainer has the required sections #1118

Closed

Description

@yakew7

Where: a new scripts/check_explainer_structure.py (or an extension of scripts/check_explainer_count.py), Makefile, .github/workflows/lint.yml, .pre-commit-config.yaml, tests/.

Current gap: CONTRIBUTING.md section 8 lists the sections a good explainer has (definition, why it matters, concrete example, detection code, limitations, related concepts, further reading) and the explainer template adds a footer line. Nothing checks it. Four explainers have no Limitations section (proxy-variables, sampling-bias, neural-networks, automation-bias), and the heading wording varies ("Why It Matters" against "Why This Matters"), so a reader cannot rely on the structure and a contributor can merge an explainer that skips a required part.

Suggested approach: define the required sections with their accepted heading variants (a small table in the script), check each explainers/*.md for them in order, for a python fenced block, for at least two Further Reading entries and for the footer line, and print the file and what is missing. Start with a list of known exceptions for the four pages above (to be removed when the Limitations sections are added) so the check can land first.

Done when: make lint and the lint workflow fail on an explainer missing a required section, the exceptions list is empty once the four pages are fixed, and the check has tests.

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

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions