From dad5dcc128b96a023fe9c4324778c16030a7bd93 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Simon=20B=C3=A4rlocher?= Date: Mon, 15 Jun 2026 22:52:54 +0200 Subject: [PATCH 1/2] ci(pull-request): add Sphinx linkcheck to catch dead external links MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Internal :ref:/:doc: references are already enforced by the nitpicky html build; add a linkcheck step that reuses the rst/ tree build.sh generates to validate external URLs. Harden against flaky endpoints with retries, a timeout, and an ignore list for hosts that 403 non-browser clients (galaxy.ansible.com, hub.docker.com). Signed-off-by: Simon Bärlocher --- .github/workflows/pull-request.yml | 7 +++++++ conf.py | 17 +++++++++++++++++ 2 files changed, 24 insertions(+) diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml index b02c81c..8af69d2 100644 --- a/.github/workflows/pull-request.yml +++ b/.github/workflows/pull-request.yml @@ -39,6 +39,13 @@ jobs: - name: Build Documentation run: ./build.sh + # Reuse the rst/ tree that build.sh already generated (collections + # rendered + normalized) and validate every external link. Internal + # :ref:/:doc: references are already enforced by the nitpicky html + # build above; this catches dead external URLs. + - name: Check Links + run: sphinx-build -b linkcheck rst build/linkcheck -c . + security-secrets: name: Secret Detection Scan uses: arillso/.github/.github/workflows/security-secrets.yml@2026-06-14 diff --git a/conf.py b/conf.py index d5eb5ea..f885ad2 100644 --- a/conf.py +++ b/conf.py @@ -65,6 +65,23 @@ nitpicky = True +# Link checking (sphinx-build -b linkcheck). Internal :ref:/:doc: references are +# validated by the regular html build (nitpicky); these options harden the +# external HTTP checks against flaky endpoints so CI fails only on genuinely +# broken links. +linkcheck_retries = 2 +linkcheck_timeout = 15 +linkcheck_workers = 5 +# Treat anchor-only failures as warnings, not errors: many sites render anchors +# client-side, so a missing #fragment is not a broken page. +linkcheck_anchors = False +# Hosts that rate-limit or block automated HEAD/GET requests but are known-good. +linkcheck_ignore = [ + # galaxy.ansible.com / hub.docker.com return 403 to non-browser clients. + r"https://galaxy\.ansible\.com/.*", + r"https://hub\.docker\.com/.*", +] + # Sitemap configuration html_baseurl = "https://guide.arillso.io/" sitemap_url_scheme = "{link}" From 07aa83134397fd241e4e6b3d76d15a4bf4562b8d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Simon=20B=C3=A4rlocher?= Date: Mon, 15 Jun 2026 23:01:15 +0200 Subject: [PATCH 2/2] fix(docs): repair dead links surfaced by linkcheck MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The new linkcheck step caught genuine broken links: - compatibility.rst: 'ansible.*/issues' and 'ansible.*/releases.atom' used a literal '.*' glob as a URL; rewrite as prose listing the real per-collection repositories. - standards.rst: linked a non-existent STANDARDS.md in arillso/.github (404); point at the repository root instead. - conf.py: ignore the 'tag:' URI scheme that appears in generated collection RST (tailscale_role ACL tags), which linkcheck cannot resolve and which lives in generated output we do not edit. Signed-off-by: Simon Bärlocher --- conf.py | 3 +++ rst/guide/best-practices/standards.rst | 2 +- rst/guide/reference/compatibility.rst | 13 +++++++++---- 3 files changed, 13 insertions(+), 5 deletions(-) diff --git a/conf.py b/conf.py index f885ad2..8d8749c 100644 --- a/conf.py +++ b/conf.py @@ -80,6 +80,9 @@ # galaxy.ansible.com / hub.docker.com return 403 to non-browser clients. r"https://galaxy\.ansible\.com/.*", r"https://hub\.docker\.com/.*", + # Non-HTTP URI schemes that appear in generated collection RST (e.g. the + # tailscale_role "tag:" ACL tags) and that linkcheck cannot resolve. + r"^tag:.*", ] # Sitemap configuration diff --git a/rst/guide/best-practices/standards.rst b/rst/guide/best-practices/standards.rst index 8816c5a..b241a96 100644 --- a/rst/guide/best-practices/standards.rst +++ b/rst/guide/best-practices/standards.rst @@ -568,4 +568,4 @@ Files to Avoid * :ref:`contributing` - How to contribute (code style, testing, development) * :ref:`cicd` - CI/CD workflows and linter configurations * :ref:`compatibility` - Version requirements and platform support - * `STANDARDS.md on GitHub `_ + * `arillso/.github on GitHub `_ - shared org standards and reusable workflows diff --git a/rst/guide/reference/compatibility.rst b/rst/guide/reference/compatibility.rst index 9cd01a6..a8caa09 100644 --- a/rst/guide/reference/compatibility.rst +++ b/rst/guide/reference/compatibility.rst @@ -665,9 +665,12 @@ Current Known Issues Version-Specific Issues ~~~~~~~~~~~~~~~~~~~~~~~ -Issues are tracked per version in GitHub Issues. - -See: https://github.com/arillso/ansible.*/issues +Issues are tracked per version in GitHub Issues, in each collection's +repository (for example `arillso/ansible.system +`_, +`arillso/ansible.agent `_, +and `arillso/ansible.container +`_). Compatibility Checklist ----------------------- @@ -742,7 +745,9 @@ Release Schedule **Subscribe to releases:** * GitHub: Watch → Custom → Releases -* RSS: https://github.com/arillso/ansible.*/releases.atom +* RSS: each collection exposes a release feed at + ``https://github.com/arillso//releases.atom`` (for example + `ansible.system `_) Next Steps ----------