You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Add a lint check that every explainer has the required sections #1118
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.
Activity
Test check_broken_links and freeze(), add an explainer structure check