docs: adjust intersphinx links & fix building docs with Python 3.14

dependencies/tox-docs-constraints.in

@@ -0,0 +1,17 @@
+###############################################################################
+#                                                                             #
+# This file is only meant to exclude broken dependency versions, not feature  #
+# dependencies.                                                               #
+#                                                                             #
+# GUIDELINES:                                                                 #
+#   1. Only list PyPI project versions that need to be excluded using `!=`    #
+#      and `<`.                                                               #
+#   2. It is allowed to have transitive dependency limitations in this file.  #
+#   3. Apply bare minimum constraints under narrow conditions, use            #
+#      environment markers if possible. E.g.  `; python_version < "3.12"`.    #
+#   4. Whenever there are no constraints, let the file and this header        #
+#      remain in Git.                                                         #
+#                                                                             #
+###############################################################################
+
+docutils < 0.22  # https://github.com/executablebooks/sphinx-tabs/pull/207

dependencies/tox-docs.in

@@ -1,3 +1,4 @@
+-c tox-docs-constraints.in  # limits known broken versions
 -r tests.in  # `sphinxcontrib-autodoc` will import all the files
 
 Sphinx >= 1.8.2

docs/changelog-fragments.d/811.contrib.rst

@@ -0,0 +1,3 @@
+Documentation building: adjusted :mod:`~sphinx.ext.intersphinx` links to remove
+warnings
+-- by :user:`mr-c`

docs/changelog-fragments.d/811.packaging.rst

@@ -0,0 +1,5 @@
+Constrained the version of docutils to before 0.22 so that the sphinx-tabs plugin
+continues to work. Can be reverted once
+`<https://github.com/executablebooks/sphinx-tabs/pull/207>`__ is merged and a
+new release of sphinx-tabs is made
+-- by :user:`mr-c`.

docs/conf.py

@@ -80,15 +80,12 @@
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3', None),
     'python2': ('https://docs.python.org/2', None),
-    # Ref: https://github.com/cherrypy/cherrypy/issues/1872
-    'cherrypy': (
-        'https://docs.cherrypy.dev/en/latest',
-        ('https://cherrypy.rtfd.io/en/latest', None),
-    ),
+    'cherrypy': ('https://docs.cherrypy.dev/en/latest', None),
     'trustme': ('https://trustme.readthedocs.io/en/latest/', None),
     'ddt': ('https://ddt.readthedocs.io/en/latest/', None),
     'pyopenssl': ('https://www.pyopenssl.org/en/latest/', None),
-    'towncrier': ('https://towncrier.rtfd.io/en/latest', None),
+    'towncrier': ('https://towncrier.readthedocs.io/en/latest/', None),
+    'sphinx': ('https://www.sphinx-doc.org', None),
 }
 
 linkcheck_ignore = [

docs/spelling_wordlist.txt

@@ -21,6 +21,7 @@ Fortran
 hardcoded
 hostname
 inclusivity
+intersphinx
 iterable
 linter
 linters

pyproject.toml

@@ -77,6 +77,7 @@ docs = [
   "sphinx >= 1.8.2",
   "jaraco.packaging >= 3.2",
   "sphinx-tabs >= 1.1.0",
+  "docutils < 0.22",  # https://github.com/executablebooks/sphinx-tabs/pull/207
 
   # local
   "furo",