Enable link check during documentation build and fix broken (#2326)

Author: gaborbernat

docs/changelog.rst

@@ -0,0 +1 @@
+Enable link check during documentation build - by :user:`gaborbernat`.

docs/changelog/2309.bugfix.rst renamed to docs/changelog/2324.bugfix.rst

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-import os
+import re
 import sys
 from datetime import date, datetime
 from pathlib import Path
@@ -17,6 +17,7 @@
 from sphinx.domains.std import StandardDomain
 from sphinx.environment import BuildEnvironment
 from sphinx.ext.autodoc import Options
+from sphinx.ext.extlinks import ExternalLinksChecker
 from sphinx.locale import __
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.logging import getLogger
@@ -77,7 +78,10 @@
 extlinks = {
     "issue": ("https://github.com/tox-dev/tox/issues/%s", "#"),
     "pull": ("https://github.com/tox-dev/tox/pull/%s", "PR #"),
+    "discussion": ("https://github.com/tox-dev/tox/discussions/%s", "#"),
     "user": ("https://github.com/%s", "@"),
+    "gh_repo": ("https://github.com/%s", ""),
+    "gh": ("https://github.com/%s", ""),
     "pypi": ("https://pypi.org/project/%s", ""),
 }
 intersphinx_mapping = {
@@ -86,8 +90,9 @@
 }
 nitpicky = True
 nitpick_ignore = []
-
-os.environ["FORCE_COLOR"] = "yes"  # force --colored default value to be yes
+linkcheck_workers = 10
+linkcheck_ignore = [re.escape(r"https://github.com/tox-dev/tox/issues/new?title=Trouble+with+development+environment")]
+extlinks_detect_hardcoded_links = True
 
 
 def skip_member(app: Sphinx, what: str, name: str, obj: Any, would_skip: bool, options: Options) -> bool:  # noqa: U100
@@ -132,23 +137,15 @@ def resolve_xref(
             # fixup some wrongly resolved mappings
             mapping = {
                 "_io.TextIOWrapper": "io.TextIOWrapper",
-                "T": "typing.TypeVar",
-                "V": "typing.TypeVar",
-                "tox.config.of_type.T": "typing.TypeVar",
-                "tox.config.loader.api.T": "typing.TypeVar",
-                "tox.config.loader.convert.T": "typing.TypeVar",
-                "tox.tox_env.installer.T": "typing.TypeVar",
-                "ToxParserT": "typing.TypeVar",
-                "_Section": "Section",
+                "tox.config.of_type.T": "typing.TypeVar",  # used by Sphinx bases
+                "tox.config.loader.api.T": "typing.TypeVar",  # used by Sphinx bases
+                "tox.config.loader.convert.T": "typing.TypeVar",  # used by Sphinx bases
+                "tox.tox_env.installer.T": "typing.TypeVar",  # used by Sphinx bases
                 "concurrent.futures._base.Future": "concurrent.futures.Future",
             }
             if target in mapping:
-                if target == "Factory":
-                    type = "attr"
-                node["reftarget"] = mapping[target]
-                if target == "_Section":
-                    target = "Section"
-                    contnode = Text(target, target)
+                target = node["reftarget"] = mapping[target]
+                # node.children[0].children[0] = Text(target, target)
             return super().resolve_xref(env, fromdocname, builder, type, target, node, contnode)
 
     app.connect("autodoc-skip-member", skip_member)
@@ -240,3 +237,10 @@ def _register_ref(self, ref_name: str, ref_title: str, node: Element) -> None:
             self._std_domain.labels[of_name] = doc_name, ref_name, ref_title
 
     app.add_directive(ToxConfig.name, ToxConfig)
+
+    def check_uri(self, refnode: reference) -> None:
+        if refnode.document.attributes["source"].endswith("index.rst"):
+            return  # do not use for the index file
+        return prev_check(self, refnode)
+
+    prev_check, ExternalLinksChecker.check_uri = ExternalLinksChecker.check_uri, check_uri

docs/changelog/2318.bugfix.rst renamed to docs/changelog/2325.bugfix.rst

@@ -9,16 +9,14 @@ Getting started
 below will help you get started with development, testing, and documentation. We’re pleased that you are interested in
 working on tox. This document is meant to get you setup to work on tox and to act as a guide and reference
 to the development setup. If you face any issues during this process, please
-`open an issue <https://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Ftox-dev%2Ftox%2Fissues%2Fnew%3Ftitle%3DTrouble%2Bwith%2Bdevelopment%2Benvironment>`_
-about it on the issue tracker.
+:issue:`new?title=Trouble+with+development+environment` about it on the issue tracker.
 
 Setup
 ~~~~~
 
 tox is a command line application written in Python. To work on it, you'll need:
 
-- **Source code**: available on `GitHub <https://github.com/tox-dev/tox>`_. You can use ``git`` to clone the
-  repository:
+- **Source code**: available on :gh_repo:`GitHub <tox-dev/tox>`. You can use ``git`` to clone the repository:
 
   .. code-block:: shell
 
@@ -150,11 +148,10 @@ or whitespace within lines. Such changes can be made separately, as a "formattin
 Automated testing
 ~~~~~~~~~~~~~~~~~
 
-All pull requests and merges to the ``master`` branch are tested using
-`GitHub Actions <https://github.com/features/actions>`_ (configured by ``check.yml`` file inside the
-``.github/workflows`` directory). You can find the status and the results to the CI runs for your
-PR on GitHub's Web UI for the pull request. You can also find links to the CI services' pages for the specific builds in
-the form of "Details" links, in case the CI run fails and you wish to view the output.
+All pull requests and merges to the ``master`` branch are tested using :gh:`GitHub Actions <features/actions>`
+(configured by ``check.yml`` file inside the ``.github/workflows`` directory). You can find the status and the results
+to the CI runs for your PR on GitHub's Web UI for the pull request. You can also find links to the CI services' pages
+for the specific builds in the form of "Details" links, in case the CI run fails and you wish to view the output.
 
 To trigger CI to run again for a pull request, you can close and open the pull request or submit another change to the
 pull request. If needed, project maintainers can manually trigger a restart of a job/build.
@@ -226,8 +223,8 @@ initiate a vote among the existing maintainers.
 Current maintainers
 ^^^^^^^^^^^^^^^^^^^
 
--  `Anthony Sottile <https://github.com/asottile>`_
--  `Bernát Gábor <https://github.com/gaborbernat>`_
--  `Jürgen Gmach <https://github.com/jugmac00>`_
--  `Miroslav Šedivý <https://github.com/eumiro>`_
--  `Oliver Bestwalter <https://github.com/obestwalter>`_
+-  :user:`Anthony Sottile <asottile>`
+-  :user:`Bernát Gábor <gaborbernat>`
+-  :user:`Jürgen Gmach <jugmac00>`
+-  :user:`Miroslav Šedivý <eumiro>`
+-  :user:`Oliver Bestwalter <obestwalter>`

docs/changelog/806.doc.rst

@@ -32,8 +32,8 @@ wheel
 Installing tox via a wheel (default with pip) requires an installer that can understand the ``python-requires`` tag (see
 `PEP-503 <https://www.python.org/dev/peps/pep-0503/>`_), with pip this is version ``9.0.0`` (released in November 2016).
 Furthermore, in case you're not installing it via PyPI you need to use a mirror that correctly forwards the
-``python-requires`` tag (notably the OpenStack mirrors don't do this, or older `devpi <https://github.com/devpi/devpi>`_
-versions - added with version ``4.7.0``).
+``python-requires`` tag (notably the OpenStack mirrors don't do this, or older :gh_repo:`devpi/devpi` versions -
+added with version ``4.7.0``).
 
 .. _sdist:
 
@@ -42,8 +42,8 @@ sdist
 When installing via a source distribution you need an installer that handles the
 `PEP-517 <https://www.python.org/dev/peps/pep-0517/>`_ specification. In case of ``pip`` this is version ``18.0.0`` or
 later (released in July 2018). If you cannot upgrade your pip to support this you need to ensure that the build
-requirements from `pyproject.toml <https://github.com/tox-dev/tox/blob/master/pyproject.toml#L2>`_ are satisfied
-before triggering the installation.
+requirements from :gh:`pyproject.toml <tox-dev/tox/blob/rewrite/pyproject.toml#L2>` are satisfied before triggering the
+installation.
 
 via ``setup.py``
 ----------------
@@ -60,7 +60,7 @@ a pip version of at least ``18.0.0`` and use the following command:
 
 .. code-block:: console
 
-    pip install git+https://github.com/tox-dev/tox.git@master
+    pip install git+https://github.com/tox-dev/tox.git@rewrite
 
 .. _compatibility-requirements:
 
@@ -69,7 +69,7 @@ Python and OS Compatibility
 
 tox works with the following Python interpreter implementations:
 
-- `CPython <https://www.python.org/>`_ versions 3.6, 3.7, 3.8, 3.9, 3.10
+- `CPython <https://www.python.org/>`_ versions 3.7, 3.8, 3.9, 3.10
 
 This means tox works on the latest patch version of each of these minor versions. Previous patch versions are supported
 on a best effort approach.

docs/conf.py

@@ -32,8 +32,8 @@ What's in for you in this:
 
 How to apply:
 
-- create an issue under the ``tox-dev/tox`` Github repository with the title `Adopt plugin \<name\>
-  <https://github.com/tox-dev/tox/issues/new?labels=feature%3Anew&template=feature_request.md&title=Adopt%20plugin&body=>`_,
+- create an issue under the ``tox-dev/tox`` Github repository with the title
+  :gh:`Adopt plugin \<name\> <login?return_to=https%3A%2F%2Fgithub.com%2Ftox-dev%2Ftox%2Fissues%2Fnew%3Flabels%3Dfeature%253Anew%26template%3Dfeature_request.md%26title%3DAdopt%2520plugin%26body%3D>`,
 - wait for the green light by one of our maintainers (see :ref:`current-maintainers`),
 - follow the `guidance by Github
   <https://docs.github.com/en/repositories/creating-and-managing-repositories/transferring-a-repository>`_,

docs/development.rst

@@ -18,6 +18,6 @@ name = "tox"
 filename = "docs/changelog.rst"
 directory = "docs/changelog"
 title_format = false
-issue_format = "`#{issue} <https://github.com/tox-dev/tox/issues/{issue}>`_"
+issue_format = ":issue:`{issue}`"
 template = "docs/changelog/template.jinja2"
 # possible types, all default: feature, bugfix, doc, removal, misc

docs/installation.rst

@@ -61,9 +61,9 @@ console_scripts =
 [options.extras_require]
 docs =
     furo>=2021.8.17b43
-    sphinx>=4.1
+    sphinx>=4.4
     sphinx-argparse-cli>=1.7
-    sphinx-autodoc-typehints>=1.15
+    sphinx-autodoc-typehints>=1.16
     sphinx-copybutton>=0.4
     sphinx-inline-tabs>=2021.4.11b9
     sphinxcontrib-towncrier>=0.2.0a0