📝 Make Sphinx strict about broken references (#2168)

Author: webknjaz

.readthedocs.yml

@@ -15,3 +15,4 @@ python:
 sphinx:
   builder: html
   configuration: docs/conf.py
+  fail_on_warning: true

docs/changelog.rst

@@ -72,7 +72,7 @@ Bugfixes
 ^^^^^^^^
 
 - Distinguish between normal Windows Python and MSYS2 Python when looking for
-  virtualenv executable path.  Adds os.sep to :class:`InterpreterInfo`
+  virtualenv executable path.  Adds os.sep to :class:`~tox.interpreters.InterpreterInfo`
   - by :user:`jschwartzentruber`
   `#1982 <https://github.com/tox-dev/tox/issues/1982>`_
 - Fix a ``tox-conda`` isolation build bug - by :user:`AntoineD`.

docs/changelog/2168.misc.rst

@@ -0,0 +1 @@
+Started enforcing valid references in Sphinx docs -- :user:`webknjaz`

docs/conf.py

@@ -129,3 +129,8 @@ def parse_node(env, text, node):
     "pull": ("https://github.com/tox-dev/tox/pull/%s", "p"),
     "user": ("https://github.com/%s", "@"),
 }
+
+nitpicky = True
+nitpick_ignore = [
+    ("py:class", "tox.interpreters.InterpreterInfo"),
+]

docs/example/basic.rst

@@ -212,7 +212,7 @@ Further customizing installation
 By default tox uses `pip`_ to install packages, both the
 package-under-test and any dependencies you specify in ``tox.ini``.
 You can fully customize tox's install-command through the
-testenv-specific :conf:`install_command=ARGV` setting.
+testenv-specific :conf:`install_command = ARGV <install_command>` setting.
 For instance, to use pip's ``--find-links`` and ``--no-index`` options to specify
 an alternative source for your dependencies:
 

docs/index.rst

@@ -137,7 +137,7 @@ Current features
 * :doc:`plugin system <plugins>` to modify tox execution with simple hooks.
 
 * uses pip_ and setuptools_ by default.  Support for configuring the installer command
-  through :conf:`install_command=ARGV`.
+  through :conf:`install_command = ARGV <install_command>`.
 
 * **cross-Python compatible**: CPython-2.7, 3.5 and higher, Jython and pypy_.
 

tox.ini

@@ -50,7 +50,7 @@ deps =
 description = invoke sphinx-build to build the HTML docs
 basepython = python3.8
 extras = docs
-commands = sphinx-build -d "{toxworkdir}/docs_doctree" docs "{toxworkdir}/docs_out" --color -W -bhtml {posargs}
+commands = sphinx-build -d "{toxworkdir}/docs_doctree" docs "{toxworkdir}/docs_out" --color -W --keep-going -n -bhtml {posargs}
            python -c 'import pathlib; print("documentation available under file://\{0\}".format(pathlib.Path(r"{toxworkdir}") / "docs_out" / "index.html"))'
 
 [testenv:package_description]