Continuously check for the broken links across the project (#1698)

* Fix broken links across the project

* Set the linkcheck workers to 25

* Add a linkcheck toxenv

* Integrate linkcheck into GHA

.github/CONTRIBUTING.rst

@@ -43,8 +43,8 @@ use `tox`_.
 
 .. _.flake8: https://github.com/ansible-community/ansible-lint/blob/main/.flake8
 .. _supported Ansible versions:
-   https://docs.ansible.com/ansible/devel/reference_appendices
-   /release_and_maintenance.html#release-status
+   https://docs.ansible.com/ansible-core/devel/reference_appendices
+   /release_and_maintenance.html#ansible-core-release-cycle
 .. _tox: https://tox.readthedocs.io
 
 .. DO-NOT-REMOVE-deps-snippet-PLACEHOLDER

.github/SECURITY.rst

@@ -5,8 +5,12 @@ Supported Versions
 ==================
 
 Ansible applies security fixes according to the 3-versions-back support
-policy. Please find more information in `our docs
-<https://docs.ansible.com/ansible/devel/reference_appendices/release_and_maintenance.html#release-status>`_.
+policy. Please find more information in `our docs`_.
+
+.. _our docs:
+   https://docs.ansible.com/ansible-core/devel/reference_appendices
+   /release_and_maintenance.html#ansible-core-release-cycle
+
 
 Reporting a Vulnerability
 =========================

.github/workflows/tox.yml

@@ -32,6 +32,7 @@ jobs:
         env:
         - TOXENV: lint
         - TOXENV: docs
+        - TOXENV: linkcheck-docs
         - TOXENV: eco
         - TOXENV: packaging
     env:

docs/conf.py

@@ -115,6 +115,8 @@
 }
 
 intersphinx_mapping = {
+    'ansible': ('https://docs.ansible.com/ansible/devel/', None),
+    'ansible-core': ('https://docs.ansible.com/ansible-core/devel/', None),
     'packaging': ('https://packaging.rtfd.io/en/latest', None),
     'pytest': ('https://docs.pytest.org/en/latest', None),
     'python': ('https://docs.python.org/3', None),
@@ -323,6 +325,8 @@
     'ansi.css',
 ]
 
+linkcheck_workers = 25
+
 nitpicky = True
 nitpick_ignore = [
     ('py:class', 'ansible.parsing.yaml.objects.AnsibleBaseYAMLObject'),

docs/usage.rst

@@ -66,10 +66,11 @@ also print errors using their `annotation`_ format.
 Linting Playbooks and Roles
 ---------------------------
 
-We recommend following the `collection structure layout`_ regardless if you
-are planning to build a collection or not. Following that layout assures the
-best integration with all ecosystem tools as it helps them better distinguish
-between random YAML files and files managed by ansible.
+We recommend following the :ref:`collection structure layout
+<collection_structure>` regardless if you are planning to build a
+collection or not. Following that layout assures the best integration
+with all ecosystem tools as it helps them better distinguish between
+random YAML files and files managed by ansible.
 
 When you call ansible-lint without arguments the tool will use its internal
 heuristics to determine file types.
@@ -83,8 +84,6 @@ arguments. The following command lints ``examples/playbooks/play.yml`` and
    :returncode: 2
    :nostderr:
 
-.. _collection structure layout: https://docs.ansible.com/ansible/devel/dev_guide/developing_collections.html#collection-structure
-
 Examples
 --------
 

src/ansiblelint/formatters/__init__.py

@@ -159,7 +159,7 @@ class CodeclimateJSONFormatter(BaseFormatter[Any]):
 
     The formatter expects a list of MatchError objects and returns a JSON formatted string.
     The spec for the codeclimate report can be found here:
-    https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-type
+    https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#user-content-data-types
     """
 
     def format_result(self, matches: List["MatchError"]) -> str:

src/ansiblelint/rules/RoleNames.py

@@ -44,8 +44,8 @@ class RoleNames(AnsibleLintRule):
     description = (
         "Role names are now limited to contain only lowercase alphanumeric "
         "characters, plus '_' and start with an alpha character. See "
-        "`developing collections <https://docs.ansible.com/ansible/devel/dev_guide/developing_"
-        "collections.html#roles-directory>`_"
+        "`developing collections <https://docs.ansible.com/ansible/devel/dev_guide/"
+        "developing_collections_structure.html#roles-directory>`_"
     )
     severity = 'HIGH'
     done: List[str] = []  # already noticed roles list

tox.ini

@@ -115,6 +115,23 @@ commands =
   'print("\n" + "=" * 120 + f"\n\nDocumentation available under `file://\{index_file\}`\n\nTo serve docs, use `python3 -m http.server --directory \{docs_dir\} 0`\n\n" + "=" * 120)'
 changedir = {toxinidir}/docs
 
+[testenv:linkcheck-docs]
+description = Linkcheck The Docs
+basepython = {[testenv:docs]basepython}
+deps = {[testenv:docs]deps}
+commands =
+  {envpython} -m sphinx \
+    -j auto \
+    -b linkcheck \
+    -a \
+    -n \
+    -W --keep-going \
+    {tty:--color} \
+    -d "{temp_dir}/.doctrees" \
+    . \
+    "{envdir}/html"
+changedir = {[testenv:docs]changedir}
+
 [testenv:eco]
 description = Perform ecosystem impact (downstream testing) https://github.com/ansible-community/ansible-lint/discussions/1403
 commands =