Resurrect docs interlinking

CHANGES.rst

@@ -22,9 +22,9 @@ v50.2.0
 
 * #2355: When pip is imported as part of a build, leave distutils patched.
 * #2380: There are some setuptools specific changes in the
-  `setuptools.command.bdist_rpm` module that are no longer needed, because
-  they are part of the `bdist_rpm` module in distutils in Python
-  3.5.0. Therefore, code was removed from `setuptools.command.bdist_rpm`.
+  ``setuptools.command.bdist_rpm`` module that are no longer needed, because
+  they are part of the ``bdist_rpm`` module in distutils in Python
+  3.5.0. Therefore, code was removed from ``setuptools.command.bdist_rpm``.
 
 
 v50.1.0
@@ -48,7 +48,7 @@ v50.0.2
 v50.0.1
 -------
 
-* #2357: Restored Python 3.5 support in distutils.util for missing `subprocess._optim_args_from_interpreter_flags`.
+* #2357: Restored Python 3.5 support in distutils.util for missing ``subprocess._optim_args_from_interpreter_flags``.
 * #2358: Restored AIX support on Python 3.8 and earlier.
 * #2361: Add Python 3.10 support to _distutils_hack. Get the 'Loader' abstract class
   from importlib.abc rather than importlib.util.abc (alias removed in Python
@@ -495,7 +495,7 @@ v40.7.1
 v40.7.0
 -------
 
-* #1551: File inputs for the `license` field in `setup.cfg` files now explicitly raise an error.
+* #1551: File inputs for the ``license`` field in ``setup.cfg`` files now explicitly raise an error.
 * #1180: Add support for non-ASCII in setup.cfg (#1062). Add support for native strings on some parameters (#1136).
 * #1499: ``setuptools.package_index`` no longer relies on the deprecated ``urllib.parse.splituser`` per Python #27485.
 * #1544: Added tests for PackageIndex.download (for git URLs).
@@ -545,7 +545,7 @@ v40.5.0
 
 * #1335: In ``pkg_resources.normalize_path``, fix issue on Cygwin when cwd contains symlinks.
 * #1502: Deprecated support for downloads from Subversion in package_index/easy_install.
-* #1517: Dropped use of six.u in favor of `u""` literals.
+* #1517: Dropped use of six.u in favor of ``u""`` literals.
 * #1520: Added support for ``data_files`` in ``setup.cfg``.
 * #1525: Fixed rendering of the deprecation warning in easy_install doc.
 
@@ -594,7 +594,7 @@ v40.2.0
 v40.1.1
 --------
 
-* #1465: Fix regression with `egg_info` command when tagging is used.
+* #1465: Fix regression with ``egg_info`` command when tagging is used.
 
 
 v40.1.0
@@ -631,8 +631,8 @@ v39.2.0
   a text file.
 * #1360: Fixed issue with a mismatch between the name of the package and the
   name of the .dist-info file in wheel files
-* #1364: Add `__dir__()` implementation to `pkg_resources.Distribution()` that
-  includes the attributes in the `_provider` instance variable.
+* #1364: Add ``__dir__()`` implementation to ``pkg_resources.Distribution()`` that
+  includes the attributes in the ``_provider`` instance variable.
 * #1365: Take the package_dir option into account when loading the version from
   a module attribute.
 * #1353: Added coverage badge to README.
@@ -742,7 +742,7 @@ v38.2.5
 v38.2.4
 -------
 
-* #1220: Fix `data_files` handling when installing from wheel.
+* #1220: Fix ``data_files`` handling when installing from wheel.
 
 v38.2.3
 -------
@@ -1506,7 +1506,7 @@ v25.4.0
 v25.3.0
 -------
 
-* #739 Fix unquoted libpaths by fixing compatibility between `numpy.distutils` and `distutils._msvccompiler` for numpy < 1.11.2 (Fix issue #728, error also fixed in Numpy).
+* #739 Fix unquoted libpaths by fixing compatibility between ``numpy.distutils`` and ``distutils._msvccompiler`` for numpy < 1.11.2 (Fix issue #728, error also fixed in Numpy).
 
 * #731: Bump certifi.
 
@@ -1523,21 +1523,21 @@ v25.2.0
 v25.1.6
 -------
 
-* #725: revert `library_dir_option` patch (Error is related to `numpy.distutils` and make errors on non Numpy users).
+* #725: revert ``library_dir_option`` patch (Error is related to ``numpy.distutils`` and make errors on non Numpy users).
 
 v25.1.5
 -------
 
 * #720
-* #723: Improve patch for `library_dir_option`.
+* #723: Improve patch for ``library_dir_option``.
 
 v25.1.4
 -------
 
 * #717
 * #713
 * #707: Fix Python 2 compatibility for MSVC by catching errors properly.
-* #715: Fix unquoted libpaths by patching `library_dir_option`.
+* #715: Fix unquoted libpaths by patching ``library_dir_option``.
 
 v25.1.3
 -------
@@ -3065,32 +3065,32 @@ not all users will find 1.0 a drop-in replacement for 0.9.
 
 * Issue #50: Normalized API of environment marker support. Specifically,
   removed line number and filename from SyntaxErrors when returned from
-  `pkg_resources.invalid_marker`. Any clients depending on the specific
+  ``pkg_resources.invalid_marker``. Any clients depending on the specific
   string representation of exceptions returned by that function may need to
   be updated to account for this change.
-* Issue #50: SyntaxErrors generated by `pkg_resources.invalid_marker` are
+* Issue #50: SyntaxErrors generated by ``pkg_resources.invalid_marker`` are
   normalized for cross-implementation consistency.
 * Removed ``--ignore-conflicts-at-my-risk`` and ``--delete-conflicting``
   options to easy_install. These options have been deprecated since 0.6a11.
 
 0.9.8
 -----
 
-* Issue #53: Fix NameErrors in `_vcs_split_rev_from_url`.
+* Issue #53: Fix NameErrors in ``_vcs_split_rev_from_url``.
 
 0.9.7
 -----
 
 * Issue #49: Correct AttributeError on PyPy where a hashlib.HASH object does
-  not have a `.name` attribute.
+  not have a ``.name`` attribute.
 * Issue #34: Documentation now refers to bootstrap script in code repository
   referenced by bookmark.
 * Add underscore-separated keys to environment markers (markerlib).
 
 0.9.6
 -----
 
-* Issue #44: Test failure on Python 2.4 when MD5 hash doesn't have a `.name`
+* Issue #44: Test failure on Python 2.4 when MD5 hash doesn't have a ``.name``
   attribute.
 
 0.9.5
@@ -3124,7 +3124,7 @@ not all users will find 1.0 a drop-in replacement for 0.9.
 0.9
 ---
 
-* `package_index` now validates hashes other than MD5 in download links.
+* ``package_index`` now validates hashes other than MD5 in download links.
 
 0.8
 ---
@@ -3171,7 +3171,7 @@ not all users will find 1.0 a drop-in replacement for 0.9.
 0.7.2
 -----
 
-* Issue #14: Use markerlib when the `parser` module is not available.
+* Issue #14: Use markerlib when the ``parser`` module is not available.
 * Issue #10: ``ez_setup.py`` now uses HTTPS to download setuptools from PyPI.
 
 0.7.1
@@ -3255,7 +3255,7 @@ Added several features that were slated for setuptools 0.6c12:
 ------
 
 * Distribute #27: Use public api for loading resources from zip files rather than
-  the private method `_zip_directory_cache`.
+  the private method ``_zip_directory_cache``.
 * Added a new function ``easy_install.get_win_launcher`` which may be used by
   third-party libraries such as buildout to get a suitable script launcher.
 
@@ -3321,7 +3321,7 @@ how it parses version numbers.
 * Fix 2 errors with Jython 2.5.
 * Fix 1 failure with Jython 2.5 and 2.7.
 * Disable workaround for Jython scripts on Linux systems.
-* Distribute #336: `setup.py` no longer masks failure exit code when tests fail.
+* Distribute #336: ``setup.py`` no longer masks failure exit code when tests fail.
 * Fix issue in pkg_resources where try/except around a platform-dependent
   import would trigger hook load failures on Mercurial. See pull request 32
   for details.
@@ -3332,7 +3332,7 @@ how it parses version numbers.
 
 * Fix test suite with Python 2.6.
 * Fix some DeprecationWarnings and ResourceWarnings.
-* Distribute #335: Backed out `setup_requires` superceding installed requirements
+* Distribute #335: Backed out ``setup_requires`` superceding installed requirements
   until regression can be addressed.
 
 0.6.31
@@ -3342,7 +3342,7 @@ how it parses version numbers.
 * Distribute #329: Properly close files created by tests for compatibility with
   Jython.
 * Work around Jython #1980 and Jython #1981.
-* Distribute #334: Provide workaround for packages that reference `sys.__stdout__`
+* Distribute #334: Provide workaround for packages that reference ``sys.__stdout__``
   such as numpy does. This change should address
   `virtualenv #359 <https://github.com/pypa/virtualenv/issues/359>`_ as long
   as the system encoding is UTF-8 or the IO encoding is specified in the
@@ -3351,7 +3351,7 @@ how it parses version numbers.
      PYTHONIOENCODING=utf8 pip install numpy
 
 * Fix for encoding issue when installing from Windows executable on Python 3.
-* Distribute #323: Allow `setup_requires` requirements to supercede installed
+* Distribute #323: Allow ``setup_requires`` requirements to supercede installed
   requirements. Added some new keyword arguments to existing pkg_resources
   methods. Also had to updated how __path__ is handled for namespace packages
   to ensure that when a new egg distribution containing a namespace package is
@@ -3371,16 +3371,16 @@ how it parses version numbers.
 * BB Pull Request #14: Honor file permissions in zip files.
 * Distribute #327: Merged pull request #24 to fix a dependency problem with pip.
 * Merged pull request #23 to fix https://github.com/pypa/virtualenv/issues/301.
-* If Sphinx is installed, the `upload_docs` command now runs `build_sphinx`
+* If Sphinx is installed, the ``upload_docs`` command now runs ``build_sphinx``
   to produce uploadable documentation.
-* Distribute #326: `upload_docs` provided mangled auth credentials under Python 3.
+* Distribute #326: ``upload_docs`` provided mangled auth credentials under Python 3.
 * Distribute #320: Fix check for "createable" in distribute_setup.py.
 * Distribute #305: Remove a warning that was triggered during normal operations.
 * Distribute #311: Print metadata in UTF-8 independent of platform.
 * Distribute #303: Read manifest file with UTF-8 encoding under Python 3.
 * Distribute #301: Allow to run tests of namespace packages when using 2to3.
 * Distribute #304: Prevent import loop in site.py under Python 3.3.
-* Distribute #283: Reenable scanning of `*.pyc` / `*.pyo` files on Python 3.3.
+* Distribute #283: Reenable scanning of ``*.pyc`` / ``*.pyo`` files on Python 3.3.
 * Distribute #299: The develop command didn't work on Python 3, when using 2to3,
   as the egg link would go to the Python 2 source. Linking to the 2to3'd code
   in build/lib makes it work, although you will have to rebuild the module
@@ -3390,10 +3390,10 @@ how it parses version numbers.
 * Distribute #313: Support for sdist subcommands (Python 2.7)
 * Distribute #314: test_local_index() would fail an OS X.
 * Distribute #310: Non-ascii characters in a namespace __init__.py causes errors.
-* Distribute #218: Improved documentation on behavior of `package_data` and
-  `include_package_data`. Files indicated by `package_data` are now included
+* Distribute #218: Improved documentation on behavior of ``package_data`` and
+  ``include_package_data``. Files indicated by ``package_data`` are now included
   in the manifest.
-* `distribute_setup.py` now allows a `--download-base` argument for retrieving
+* ``distribute_setup.py`` now allows a ``--download-base`` argument for retrieving
   distribute from a specified location.
 
 0.6.28
@@ -3402,7 +3402,7 @@ how it parses version numbers.
 * Distribute #294: setup.py can now be invoked from any directory.
 * Scripts are now installed honoring the umask.
 * Added support for .dist-info directories.
-* Distribute #283: Fix and disable scanning of `*.pyc` / `*.pyo` files on
+* Distribute #283: Fix and disable scanning of ``*.pyc`` / ``*.pyo`` files on
   Python 3.3.
 
 0.6.27
@@ -3636,7 +3636,7 @@ how it parses version numbers.
 0.6.4
 -----
 
-* Added the generation of `distribute_setup_3k.py` during the release.
+* Added the generation of ``distribute_setup_3k.py`` during the release.
   This closes Distribute #52.
 
 * Added an upload_docs command to easily upload project documentation to

changelog.d/2427.doc.rst

@@ -0,0 +1,2 @@
+Started enforcing strict syntax and reference validation
+in the Sphinx docs -- by :user:`webknjaz`

docs/build_meta.rst

@@ -56,7 +56,8 @@ setuptools, the content would be::
     requires = ["setuptools", "wheel"]
     build-backend = "setuptools.build_meta" 
 
-Use ``setuptools``' `declarative config`_ to specify the package information::
+Use ``setuptools``' :ref:`declarative config <declarative config>` to
+specify the package information::
 
     [metadata]
     name = meowpkg

docs/conf.py

@@ -146,3 +146,12 @@
         ],
     ),
 }
+
+
+# Be strict about any broken references:
+nitpicky = True
+
+
+# Ref: https://github.com/python-attrs/attrs/pull/571/files\
+#      #diff-85987f48f1258d9ee486e3191495582dR82
+default_role = 'any'

docs/deprecated/index.rst

@@ -17,3 +17,4 @@ objectives.
     python_eggs
     easy_install
     distutils-legacy
+    functionalities

docs/development.rst

@@ -31,5 +31,4 @@ setuptools changes.  You have been warned.
    :maxdepth: 1
 
    developer-guide
-   formats
    releases

docs/index.rst

@@ -10,5 +10,11 @@ Documentation content:
    :maxdepth: 1
 
    User guide <userguide/index>
+   build_meta
+   pkg_resources
+   references/keywords
+   roadmap
+   setuptools
    Development guide <development>
    Backward compatibility & deprecated practice <deprecated/index>
+   Changelog <history>