ev-flow / ev-flow/quark-engine

Add CI check to catch broken documentation links in README

Open
#949 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
1.7k
Forks
218
Avg merge
4d 12h
Merged PRs (30d)
7

Description

### Problem
The report links in the README point to documentation pages/anchors that don't exist (e.g. `quark_rules.html`, which is not a real page). There is currently no automated check, so broken links only get noticed when someone finds them manually. The README has 21 of these doc links.

### Plan
After the docs are built in CI, compare the README links against the build output; fail the check (blocking merge) on any mismatch.

1. Add a script `docs/check_readme_links.py` that does three things:
- Extract every link in `README.md` that points to our own docs (e.g. `.../malware_report.html#brata`, where the part after `#` is a section anchor).
- Check that the target page exists in the built docs.
- Open that page and confirm the anchor (section) actually exists in it.

If any of the three fails, the script reports failure.

2. Run this check automatically on every PR / push to `master`: checkout -> build the docs to HTML (`sphinx-build docs/source docs/_build/html`) -> run the script. If a broken link is found, the check fails and the PR cannot be merged. It is a standalone job and does not affect the existing tests. (A new workflow file `.github/workflows/docs-link-check.yml`.)

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with README.md and the planned docs/check_readme_links.py script, then inspect the existing CI workflows before adding .github/workflows/docs-link-check.yml. Build the HTML docs with `sphinx-build docs/source docs/_build/html` and run the checker against the README’s internal documentation links. Done means valid pages and anchors pass, while any missing target causes the standalone CI job to fail.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, python
Domain
ci-cd, documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.