What and why
The markdown docs (README, CONTRIBUTING, the kg family README, demo READMEs) contain many relative links and file references, and some have already drifted (see the stale docs/kg-connector-base-classes.md reference). A small linter script that checks relative markdown links against the working tree, run as a pytest, keeps them from drifting again. mloda-registry has a similar scripts/lint_docs.py that can serve as inspiration, though a much smaller version is enough here.
Pointers
Steps
- Write a small test (e.g.
tests/test_doc_links.py) that walks all committed *.md files, extracts relative link targets and inline file references in standard markdown link syntax, and asserts each target exists.
- Skip external links (
http://, https://, mailto:).
- Fix or coordinate fixes for any breakage it finds (the known stale reference has its own issue).
- Run
tox; the new test must be part of the normal pytest run and respect mypy strict mode.
Acceptance criteria
- A pytest fails when a relative markdown link points at a missing file, and passes on main once existing breakage is fixed.
tox passes.
Notes
This project uses semantic versioning driven by Conventional Commits, so the PR title matters: use a prefix like test: or feat: (e.g. test: guard relative doc links).
New to the project? This issue is a good entry point, we are happy to help in the comments.
If you like the project, a star on the repo helps others find it. ⭐
What and why
The markdown docs (README, CONTRIBUTING, the kg family README, demo READMEs) contain many relative links and file references, and some have already drifted (see the stale
docs/kg-connector-base-classes.mdreference). A small linter script that checks relative markdown links against the working tree, run as a pytest, keeps them from drifting again. mloda-registry has a similarscripts/lint_docs.pythat can serve as inspiration, though a much smaller version is enough here.Pointers
README.md,CONTRIBUTING.md,open_kgo/feature_groups/kg/README.md,demo/data/README.md,demo/data/metaqa/README.md,docs/github-workflows.mdtests/(e.g.tests/test_demo_data.py) and show the conventionsSteps
tests/test_doc_links.py) that walks all committed*.mdfiles, extracts relative link targets and inline file references in standard markdown link syntax, and asserts each target exists.http://,https://,mailto:).tox; the new test must be part of the normal pytest run and respect mypy strict mode.Acceptance criteria
toxpasses.Notes
This project uses semantic versioning driven by Conventional Commits, so the PR title matters: use a prefix like
test:orfeat:(e.g.test: guard relative doc links).New to the project? This issue is a good entry point, we are happy to help in the comments.
If you like the project, a star on the repo helps others find it. ⭐