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..8d8749c 100644 --- a/conf.py +++ b/conf.py @@ -65,6 +65,26 @@ 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/.*", + # 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 html_baseurl = "https://guide.arillso.io/" sitemap_url_scheme = "{link}" 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 ----------