Merge branch 'master' into patch-2

.bumpversion.cfg

 [bumpversion]
-current_version = 50.3.0
+current_version = 50.3.1
 commit = True
 tag = True
 

changelog.d/2093.doc.rst

-Finalized doc revamp.

changelog.d/2097.doc.rst

-doc: simplify index and group deprecated files

changelog.d/2102.doc.rst

-doc overhaul step 2: break main doc into multiple sections
\ No newline at end of file

changelog.d/2111.doc.rst

-doc overhaul step 3: update userguide

changelog.d/2379.misc.rst

-Travis CI test suite now tests against PPC64.

changelog.d/2427.doc.rst

+Started enforcing strict syntax and reference validation
+in the Sphinx docs -- by :user:`webknjaz`

changelog.d/2428.doc.rst

+Removed redundant Sphinx ``Makefile`` support -- by :user:`webknjaz`

changelog.d/README.rst

+.. _Adding change notes with your PRs:
+
+Adding change notes with your PRs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is very important to maintain a log for news of how
+updating to the new version of the software will affect
+end-users. This is why we enforce collection of the change
+fragment files in pull requests as per `Towncrier philosophy`_.
+
+The idea is that when somebody makes a change, they must record
+the bits that would affect end-users only including information
+that would be useful to them. Then, when the maintainers publish
+a new release, they'll automatically use these records to compose
+a change log for the respective version. It is important to
+understand that including unnecessary low-level implementation
+related details generates noise that is not particularly useful
+to the end-users most of the time. And so such details should be
+recorded in the Git history rather than a changelog.
+
+Alright! So how to add a news fragment?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``setuptools`` uses `towncrier <https://pypi.org/project/towncrier/>`_
+for changelog management.
+To submit a change note about your PR, add a text file into the
+``changelog.d/`` folder. It should contain an
+explanation of what applying this PR will change in the way
+end-users interact with the project. One sentence is usually
+enough but feel free to add as many details as you feel necessary
+for the users to understand what it means.
+
+**Use the past tense** for the text in your fragment because,
+combined with others, it will be a part of the "news digest"
+telling the readers **what changed** in a specific version of
+the library *since the previous version*. You should also use
+reStructuredText syntax for highlighting code (inline or block),
+linking parts of the docs or external sites.
+If you wish to sign your change, feel free to add ``-- by
+:user:`github-username``` at the end (replace ``github-username``
+with your own!).
+
+Finally, name your file following the convention that Towncrier
+understands: it should start with the number of an issue or a
+PR followed by a dot, then add a patch type, like ``change``,
+``doc``, ``misc`` etc., and add ``.rst`` as a suffix. If you
+need to add more than one fragment, you may add an optional
+sequence number (delimited with another period) between the type
+and the suffix.
+
+In general the name will follow ``<pr_number>.<category>.rst`` pattern,
+where the categories are:
+
+- ``change``: Any backwards compatible code change
+- ``breaking``: Any backwards-compatibility breaking change
+- ``doc``: A change to the documentation
+- ``misc``: Changes internal to the repo like CI, test and build changes
+- ``deprecation``: For deprecations of an existing feature or behavior
+
+A pull request may have more than one of these components, for example
+a code change may introduce a new feature that deprecates an old
+feature, in which case two fragments should be added. It is not
+necessary to make a separate documentation fragment for documentation
+changes accompanying the relevant code changes.
+
+Examples for adding changelog entries to your Pull Requests
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+File :file:`changelog.d/2395.doc.1.rst`:
+
+.. code-block:: rst
+
+    Added a ``:user:`` role to Sphinx config -- by :user:`webknjaz`
+
+File :file:`changelog.d/1354.misc.rst`:
+
+.. code-block:: rst
+
+    Added ``towncrier`` for changelog managment -- by :user:`pganssle`
+
+File :file:`changelog.d/2355.change.rst`:
+
+.. code-block:: rst
+
+    When pip is imported as part of a build, leave :py:mod:`distutils`
+    patched -- by :user:`jaraco`
+
+.. tip::
+
+   See :file:`pyproject.toml` for all available categories
+   (``tool.towncrier.type``).
+
+.. _Towncrier philosophy:
+   https://towncrier.readthedocs.io/en/actual-freaking-docs/#philosophy

conftest.py

@@ -25,4 +25,5 @@ collect_ignore = [
 
 
 if sys.version_info < (3, 6):
+    collect_ignore.append('docs/conf.py')  # uses f-strings
     collect_ignore.append('pavement.py')

docs/Makefile

-# Makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-PAPER         =
-
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-.PHONY: help clean html web pickle htmlhelp latex changes linkcheck
-
-help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html      to make standalone HTML files"
-	@echo "  pickle    to make pickle files"
-	@echo "  json      to make JSON files"
-	@echo "  htmlhelp  to make HTML files and a HTML help project"
-	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  changes   to make an overview over all changed/added/deprecated items"
-	@echo "  linkcheck to check all external links for integrity"
-
-clean:
-	-rm -rf build/*
-
-html:
-	mkdir -p build/html build/doctrees
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
-	@echo
-	@echo "Build finished. The HTML pages are in build/html."
-
-pickle:
-	mkdir -p build/pickle build/doctrees
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-web: pickle
-
-json:
-	mkdir -p build/json build/doctrees
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) build/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
-htmlhelp:
-	mkdir -p build/htmlhelp build/doctrees
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in build/htmlhelp."
-
-latex:
-	mkdir -p build/latex build/doctrees
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in build/latex."
-	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
-	      "run these through (pdf)latex."
-
-changes:
-	mkdir -p build/changes build/doctrees
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
-	@echo
-	@echo "The overview file is in build/changes."
-
-linkcheck:
-	mkdir -p build/linkcheck build/doctrees
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in build/linkcheck/output.txt."

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

@@ -10,9 +10,18 @@ import os
     cwd=os.path.join(os.path.dirname(__file__), os.path.pardir),
 )
 
+# -- Project information -----------------------------------------------------
+
+github_url = 'https://github.com'
+github_sponsors_url = f'{github_url}/sponsors'
+
 # -- General configuration --
 
-extensions = ['jaraco.packaging.sphinx', 'rst.linker']
+extensions = [
+    'sphinx.ext.extlinks',  # allows to create custom roles easily
+    'jaraco.packaging.sphinx',
+    'rst.linker',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -27,6 +36,11 @@ exclude_trees = []
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
+# -- Options for extlinks extension ---------------------------------------
+extlinks = {
+    'user': (f'{github_sponsors_url}/%s', '@'),  # noqa: WPS323
+}
+
 # -- Options for HTML output --
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
@@ -132,3 +146,12 @@ link_files = {
         ],
     ),
 }
+
+
+# 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/developer-guide.rst

@@ -61,33 +61,14 @@ jump to the in-depth discussion about any subject referenced.
 Making a pull request
 ---------------------
 
-When making a pull request, please include a short summary of the changes
-and a reference to any issue tickets that the PR is intended to solve.
-All PRs with code changes should include tests. All changes should include a
-changelog entry.
-
-``setuptools`` uses `towncrier <https://pypi.org/project/towncrier/>`_
-for changelog management, so when making a PR, please add a news fragment in the
-``changelog.d/`` folder. Changelog files are written in reStructuredText and
-should be a 1 or 2 sentence description of the substantive changes in the PR.
-They should be named ``<pr_number>.<category>.rst``, where the categories are:
-
-- ``change``: Any backwards compatible code change
-- ``breaking``: Any backwards-compatibility breaking change
-- ``doc``: A change to the documentation
-- ``misc``: Changes internal to the repo like CI, test and build changes
-- ``deprecation``: For deprecations of an existing feature or behavior
-
-A pull request may have more than one of these components, for example a code
-change may introduce a new feature that deprecates an old feature, in which
-case two fragments should be added. It is not necessary to make a separate
-documentation fragment for documentation changes accompanying the relevant
-code changes. See the following for an example news fragment:
-
-.. code-block:: bash
-
-    $ cat changelog.d/1288.change.rst
-    Add support for maintainer in PKG-INFO
+When making a pull request, please 
+:ref:`include a short summary of the changes <Adding change notes
+with your PRs>` and a reference to any issue tickets that the PR is
+intended to solve.
+All PRs with code changes should include tests. All changes should
+include a changelog entry.
+
+.. include:: ../changelog.d/README.rst
 
 -------------------
 Auto-Merge Requests

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>

docs/references/keywords.rst

+========
+Keywords
+========
+
 ``name``
     A string specifying the name of the package.
 
@@ -189,7 +193,7 @@
     discovery of services or plugins provided by a project.  See :ref:`Dynamic
     Discovery of Services and Plugins` for details and examples of the format
     of this argument.  In addition, this keyword is used to support
-    :ref:`Automatic Script Creation`.
+    :ref:`Automatic Script Creation <entry_points>`.
 
 ``extras_require``
     A dictionary mapping names of "extras" (optional features of your project)
@@ -282,7 +286,7 @@
     this argument.  The named class must be instantiable with no arguments, and
     its instances must support the ``loadTestsFromNames()`` method as defined
     in the Python ``unittest`` module's ``TestLoader`` class.  Setuptools will
-    pass only one test "name" in the `names` argument: the value supplied for
+    pass only one test "name" in the ``names`` argument: the value supplied for
     the ``test_suite`` argument.  The loader you specify may interpret this
     string in any way it likes, as there are no restrictions on what may be
     contained in a ``test_suite`` string.
@@ -317,15 +321,15 @@
 
 ``use_2to3``
     Convert the source code from Python 2 to Python 3 with 2to3 during the
-    build process. See :doc:`python3` for more details.
+    build process. See :doc:`../deprecated/python3` for more details.
 
 ``convert_2to3_doctests``
     List of doctest source files that need to be converted with 2to3.
-    See :doc:`python3` for more details.
+    See :doc:`../deprecated/python3` for more details.
 
 ``use_2to3_fixers``
     A list of modules to search for additional fixers to be used during
-    the 2to3 conversion. See :doc:`python3` for more details.
+    the 2to3 conversion. See :doc:`../deprecated/python3` for more details.
 
 ``use_2to3_exclude_fixers``
     List of fixer names to be skipped.

docs/userguide/commands.rst

@@ -275,7 +275,7 @@ is used when you are building source distributions.)
 In addition to writing the core egg metadata defined by ``setuptools`` and
 required by ``pkg_resources``, this command can be extended to write other
 metadata files as well, by defining entry points in the ``egg_info.writers``
-group.  See the section on `Adding new EGG-INFO Files`_ below for more details.
+group.  See the section on :ref:`Adding new EGG-INFO Files` below for more details.
 Note that using additional metadata writers may require you to include a
 ``setup_requires`` argument to ``setup()`` in order to ensure that the desired
 writers are available on ``sys.path``.
@@ -315,7 +315,7 @@ added in the following order:
 (Note: Because these options modify the version number used for source and
 binary distributions of your project, you should first make sure that you know
 how the resulting version numbers will be interpreted by automated tools
-like pip.  See the section above on `Specifying Your Project's Version`_ for an
+like pip.  See the section above on :ref:`Specifying Your Project's Version` for an
 explanation of pre- and post-release tags, as well as tips on how to choose and
 verify a versioning scheme for your project.)
 

docs/userguide/datafiles.rst

@@ -20,8 +20,8 @@ e.g.::
 This tells setuptools to install any data files it finds in your packages.
 The data files must be specified via the distutils' ``MANIFEST.in`` file.
 (They can also be tracked by a revision control system, using an appropriate
-plugin.  See the section below on `Adding Support for Revision Control
-Systems`_ for information on how to write such plugins.)
+plugin.  See the section below on :ref:`Adding Support for Revision
+Control Systems` for information on how to write such plugins.)
 
 If you want finer-grained control over what files are included (for example,
 if you have documentation files in your package directories and want to exclude
@@ -144,6 +144,9 @@ if they track intermediate revisions of your project using Subversion; be sure
 to let them know when you make changes that remove files from inclusion so they
 can run ``setup.py clean --all``.
 
+
+.. _Accessing Data Files at Runtime:
+
 Accessing Data Files at Runtime
 -------------------------------
 
@@ -171,4 +174,4 @@ fall back to the platform-specific location for installing data files, there is
 no supported facility to reliably retrieve these resources.
 
 Instead, the PyPA recommends that any data files you wish to be accessible at
-run time be included in the package.
\ No newline at end of file
+run time be included in the package.

docs/userguide/declarative_config.rst

+.. _declarative config:
+
 -----------------------------------------
 Configuring setup() using setup.cfg files
 -----------------------------------------
@@ -199,7 +201,7 @@ obsoletes                                          list-comma
     string in such a file, so validation is stricter in this case.
 
 Notes:
-1. The `version` file attribute has only been supported since 39.2.0.
+1. The ``version`` file attribute has only been supported since 39.2.0.
 
 Options
 -------
@@ -235,12 +237,12 @@ data_files               dict                                 40.6.0
 
     **packages** - The ``find:`` and ``find_namespace:`` directive can be further configured
     in a dedicated subsection ``options.packages.find``. This subsection
-    accepts the same keys as the `setuptools.find_packages` and the
-    `setuptools.find_namespace_packages` function:
+    accepts the same keys as the ``setuptools.find_packages`` and the
+    ``setuptools.find_namespace_packages`` function:
     ``where``, ``include``, and ``exclude``.
 
     **find_namespace directive** - The ``find_namespace:`` directive is supported since Python >=3.3.
 
 Notes:
-1. In the `package_data` section, a key named with a single asterisk (`*`)
-refers to all packages, in lieu of the empty string used in `setup.py`.
+1. In the ``package_data`` section, a key named with a single asterisk (``*``)
+refers to all packages, in lieu of the empty string used in ``setup.py``.

docs/userguide/dependency_management.rst

@@ -25,7 +25,7 @@ you also need the ``wheel`` package as well since it is recommended that you
 upload a ``.whl`` file to PyPI alongside your ``.tar.gz`` file. Unlike the
 other two types of dependency keyword, this one is specified in your
 ``pyproject.toml`` file (if you have forgot what this is, go to
-:ref:`quickstart` or (WIP)):
+:doc:`quickstart` or (WIP)):
 
 .. code-block:: ini
 
@@ -36,10 +36,11 @@ other two types of dependency keyword, this one is specified in your
 .. note::
     This used to be accomplished with the ``setup_requires`` keyword but is
     now considered deprecated in favor of the PEP 517 style described above.
-    To peek into how this legacy keyword is used, consult our :ref:`guide on
-    deprecated practice (WIP)`
+    To peek into how this legacy keyword is used, consult our :doc:`guide on
+    deprecated practice (WIP) <../deprecated/index>`
 
 
+.. _Declaring Dependencies:
 
 Declaring required dependency
 =============================

docs/userguide/development_mode.rst

@@ -49,7 +49,7 @@ source from a staging area using ``setup.py develop --uninstall``, specifying
 the desired staging area if it's not the default.
 
 There are several options to control the precise behavior of the ``develop``
-command; see the section on the `develop`_ command below for more details.
+command; see the section on the :ref:`develop <develop>` command below for more details.
 
 Note that you can also apply setuptools commands to non-setuptools projects,
 using commands like this::
@@ -57,4 +57,4 @@ using commands like this::
    python -c "import setuptools; with open('setup.py') as f: exec(compile(f.read(), 'setup.py', 'exec'))" develop
 
 That is, you can simply list the normal setup commands and options following
-the quoted part.
\ No newline at end of file
+the quoted part.

docs/userguide/distribution.rst

@@ -23,17 +23,17 @@ egg distributions by adding one or more of the following to the project's
 You can add these tags by adding ``egg_info`` and the desired options to
 the command line ahead of the ``sdist`` or ``bdist`` commands that you want
 to generate a daily build or snapshot for.  See the section below on the
-`egg_info`_ command for more details.
+:ref:`egg_info <egg_info>` command for more details.
 
 (Also, before you release your project, be sure to see the section above on
-`Specifying Your Project's Version`_ for more information about how pre- and
+:ref:`Specifying Your Project's Version` for more information about how pre- and
 post-release tags affect how version numbers are interpreted.  This is
 important in order to make sure that dependency processing tools will know
 which versions of your project are newer than others.)
 
 Finally, if you are creating builds frequently, and either building them in a
 downloadable location or are copying them to a distribution server, you should
-probably also check out the `rotate`_ command, which lets you automatically
+probably also check out the :ref:`rotate <rotate>` command, which lets you automatically
 delete all but the N most-recently-modified distributions matching a glob
 pattern.  So, you can use a command line like::
 
@@ -46,7 +46,7 @@ that were built most recently.
 
 If you have to manage automated builds for multiple packages, each with
 different tagging and rotation policies, you may also want to check out the
-`alias`_ command, which would let each package define an alias like ``daily``
+:ref:`alias <alias>` command, which would let each package define an alias like ``daily``
 that would perform the necessary tag, build, and rotate commands.  Then, a
 simpler script or cron job could just run ``setup.py daily`` in each project
 directory.  (And, you could also define sitewide or per-user default versions
@@ -61,7 +61,7 @@ selection with pluggable endpoints for looking up files to include. If you are
 using a revision control system, and your source distributions only need to
 include files that you're tracking in revision control, use a corresponding
 plugin instead of writing a ``MANIFEST.in`` file. See the section below on
-`Adding Support for Revision Control Systems`_ for information on plugins.
+:ref:`Adding Support for Revision Control Systems` for information on plugins.
 
 If you need to include automatically generated files, or files that are kept in
 an unsupported revision control system, you'll need to create a ``MANIFEST.in``
@@ -114,7 +114,8 @@ You can then use it like this::
     setup.py release sdist bdist_egg
 
 Or of course you can create more elaborate aliases that do all of the above.
-See the sections below on the `egg_info`_ and `alias`_ commands for more ideas.
+See the sections below on the :ref:`egg_info <egg_info>` and
+:ref:`alias <alias>` commands for more ideas.
 
 Distributing Extensions compiled with Cython
 --------------------------------------------
@@ -154,6 +155,9 @@ control system will be able to build it even if they don't have Cython
 installed, and that your source releases will be similarly usable with or
 without Cython.
 
+
+.. _Specifying Your Project's Version:
+
 Specifying Your Project's Version
 ---------------------------------
 
@@ -237,4 +241,4 @@ have setuptools automatically tag your in-development releases with various
 pre- or post-release tags.  See the following sections for more details:
 
 * `Tagging and "Daily Build" or "Snapshot" Releases`_
-* The `egg_info`_ command
\ No newline at end of file
+* The :ref:`egg_info <egg_info>` command

docs/userguide/entry_point.rst

@@ -76,6 +76,8 @@ In addition to ``console_scripts``, Setuptools supports ``gui_scripts``, which
 will launch a GUI application without running in a terminal window.
 
 
+.. _dynamic discovery of services and plugins:
+
 Advertising Behavior
 ====================
 
@@ -140,7 +142,7 @@ Some entry points may require additional dependencies to properly function.
 For such an entry point, declare in square brakets any number of dependency
 ``extras`` following the entry point definition. Such entry points will only
 be viable if their extras were declared and installed. See the
-:ref:`guide on dependencies management <dependency_management>` for
+:doc:`guide on dependencies management <dependency_management>` for
 more information on defining extra requirements. Consider from the
 above example:
 

docs/userguide/extension.rst

+.. _Creating ``distutils`` Extensions:
+
 Creating ``distutils`` Extensions
 =================================
 
@@ -9,8 +11,8 @@ the extension just refer to it in their ``setup_requires`` argument.
 With ``setuptools``, your distutils extension projects can hook in new
 commands and ``setup()`` arguments just by defining "entry points".  These
 are mappings from command or argument names to a specification of where to
-import a handler from.  (See the section on `Dynamic Discovery of Services and
-Plugins`_ above for some more background on entry points.)
+import a handler from.  (See the section on :ref:`Dynamic Discovery of
+Services and Plugins` above for some more background on entry points.)
 
 
 Adding Commands
@@ -120,6 +122,8 @@ plugin is encouraged to load the configuration/settings for their behavior
 independently.
 
 
+.. _Adding new EGG-INFO Files:
+
 Adding new EGG-INFO Files
 -------------------------
 
@@ -173,6 +177,9 @@ the ``cmd`` object's ``write_file()``, ``delete_file()``, and
 ``write_or_delete_file()`` methods exclusively for your file operations.  See
 those methods' docstrings for more details.
 
+
+.. _Adding Support for Revision Control Systems:
+
 Adding Support for Revision Control Systems
 -------------------------------------------------
 
@@ -232,4 +239,4 @@ A few important points for writing revision control file finders:
 * Your finder function SHOULD NOT raise any errors, and SHOULD deal gracefully
   with the absence of needed programs (i.e., ones belonging to the revision
   control system itself.  It *may*, however, use ``distutils.log.warn()`` to
-  inform the user of the missing program(s).
\ No newline at end of file
+  inform the user of the missing program(s).

docs/userguide/index.rst

@@ -24,3 +24,5 @@ ordinary Python packages based on the ``distutils``.
     declarative_config
     keywords
     commands
+    functionalities_rewrite
+    miscellaneous

docs/userguide/keywords.rst

@@ -8,19 +8,19 @@ unless you need the associated ``setuptools`` feature.
 ``include_package_data``
     If set to ``True``, this tells ``setuptools`` to automatically include any
     data files it finds inside your package directories that are specified by
-    your ``MANIFEST.in`` file.  For more information, see the section below on
-    `Including Data Files`_.
+    your ``MANIFEST.in`` file.  For more information, see the section on
+    :ref:`Including Data Files`.
 
 ``exclude_package_data``
     A dictionary mapping package names to lists of glob patterns that should
     be *excluded* from your package directories.  You can use this to trim back
     any excess files included by ``include_package_data``.  For a complete
-    description and examples, see the section below on `Including Data Files`_.
+    description and examples, see the section on :ref:`Including Data Files`.
 
 ``package_data``
     A dictionary mapping package names to lists of glob patterns.  For a
-    complete description and examples, see the section below on `Including
-    Data Files`_.  You do not need to use this option if you are using
+    complete description and examples, see the section on :ref:`Including
+    Data Files`.  You do not need to use this option if you are using
     ``include_package_data``, unless you need to add e.g. files that are
     generated by your setup script and build process.  (And are therefore not
     in source control or are files that you don't want to include in your
@@ -34,22 +34,22 @@ unless you need the associated ``setuptools`` feature.
 
 ``install_requires``
     A string or list of strings specifying what other distributions need to
-    be installed when this one is.  See the section below on `Declaring
-    Dependencies`_ for details and examples of the format of this argument.
+    be installed when this one is.  See the section on :ref:`Declaring
+    Dependencies` for details and examples of the format of this argument.
 
 ``entry_points``
     A dictionary mapping entry point group names to strings or lists of strings
     defining the entry points.  Entry points are used to support dynamic
-    discovery of services or plugins provided by a project.  See `Dynamic
-    Discovery of Services and Plugins`_ for details and examples of the format
-    of this argument.  In addition, this keyword is used to support `Automatic
-    Script Creation`_.
+    discovery of services or plugins provided by a project.  See :ref:`Dynamic
+    Discovery of Services and Plugins` for details and examples of the format
+    of this argument.  In addition, this keyword is used to support
+    :ref:`Automatic Script Creation <entry_points>`.
 
 ``extras_require``
     A dictionary mapping names of "extras" (optional features of your project)
     to strings or lists of strings specifying what other distributions must be
-    installed to support those features.  See the section below on `Declaring
-    Dependencies`_ for details and examples of the format of this argument.
+    installed to support those features.  See the section on :ref:`Declaring
+    Dependencies` for details and examples of the format of this argument.
 
 ``python_requires``
     A string corresponding to a version specifier (as defined in PEP 440) for
@@ -87,7 +87,7 @@ unless you need the associated ``setuptools`` feature.
     as you declare them in each project that contains any subpackages of the
     namespace package, and as long as the namespace package's ``__init__.py``
     does not contain any code other than a namespace declaration.  See the
-    section below on `Namespace Packages`_ for more information.
+    section below on :ref:`Namespace Packages` for more information.
 
 ``test_suite``
     A string naming a ``unittest.TestCase`` subclass (or a package or module
@@ -98,9 +98,9 @@ unless you need the associated ``setuptools`` feature.
     added to the tests to be run.  If the named suite is a package, any
     submodules and subpackages are recursively added to the overall test suite.
 
-    Specifying this argument enables use of the `test`_ command to run the
+    Specifying this argument enables use of the :ref:`test <test>` command to run the
     specified test suite, e.g. via ``setup.py test``.  See the section on the
-    `test`_ command below for more details.
+    :ref:`test <test>` command below for more details.
 
     New in 41.5.0: Deprecated the test command.
 
@@ -124,7 +124,7 @@ unless you need the associated ``setuptools`` feature.
     this argument.  The named class must be instantiable with no arguments, and
     its instances must support the ``loadTestsFromNames()`` method as defined
     in the Python ``unittest`` module's ``TestLoader`` class.  Setuptools will
-    pass only one test "name" in the `names` argument: the value supplied for
+    pass only one test "name" in the ``names`` argument: the value supplied for
     the ``test_suite`` argument.  The loader you specify may interpret this
     string in any way it likes, as there are no restrictions on what may be
     contained in a ``test_suite`` string.
@@ -155,21 +155,21 @@ unless you need the associated ``setuptools`` feature.
     extensions that access other files in the project (such as data files or
     shared libraries), you probably do NOT need this argument and shouldn't
     mess with it.  For more details on how this argument works, see the section
-    below on `Automatic Resource Extraction`_.
+    below on :ref:`Automatic Resource Extraction`.
 
 ``use_2to3``
     Convert the source code from Python 2 to Python 3 with 2to3 during the
-    build process. See :doc:`python3` for more details.
+    build process. See :doc:`../deprecated/python3` for more details.
 
 ``convert_2to3_doctests``
     List of doctest source files that need to be converted with 2to3.
-    See :doc:`python3` for more details.
+    See :doc:`../deprecated/python3` for more details.
 
 ``use_2to3_fixers``
     A list of modules to search for additional fixers to be used during
-    the 2to3 conversion. See :doc:`python3` for more details.
+    the 2to3 conversion. See :doc:`../deprecated/python3` for more details.
 
 ``project_urls``
     An arbitrary map of URL names to hyperlinks, allowing more extensible
     documentation of where various resources can be found than the simple
-    ``url`` and ``download_url`` options provide.
\ No newline at end of file
+    ``url`` and ``download_url`` options provide.

docs/userguide/miscellaneous.rst

+.. _Automatic Resource Extraction:
+
 Automatic Resource Extraction
 -----------------------------
 
@@ -46,8 +48,8 @@ directory.  However, since it can be tedious to create such files by hand, you
 may want to create a distutils extension that will create the necessary files
 from arguments to ``setup()``, in much the same way that ``setuptools`` does
 for many of the ``setup()`` arguments it adds.  See the section below on
-`Creating distutils Extensions`_ for more details, especially the subsection on
-`Adding new EGG-INFO Files`_.
+:ref:`Creating ``distutils\`\` Extensions` for more details, especially the
+subsection on :ref:`Adding new EGG-INFO Files`.
 
 Setting the ``zip_safe`` flag
 -----------------------------
@@ -75,7 +77,7 @@ no ``__file__`` or ``__path__`` introspection or source code manipulation, then
 there is an extremely solid chance the project will work when installed as a
 zipfile.  (And if the project uses ``pkg_resources`` for all its data file
 access, then C extensions and other data files shouldn't be a problem at all.
-See the `Accessing Data Files at Runtime`_ section above for more information.)
+See the :ref:`Accessing Data Files at Runtime` section above for more information.)
 
 However, if ``bdist_egg`` can't be *sure* that your package will work, but
 you've checked over all the warnings it issued, and you are either satisfied it

docs/userguide/package_discovery.rst

@@ -6,13 +6,13 @@ Package Discovery and Namespace Package
 
 .. note::
     a full specification for the keyword supplied to ``setup.cfg`` or
-    ``setup.py`` can be found at :ref:`keywords reference <keywords_ref>`
+    ``setup.py`` can be found at :doc:`keywords reference <keywords>`
 
 .. note::
     the examples provided here are only to demonstrate the functionality
     introduced. More metadata and options arguments need to be supplied
     if you want to replicate them on your system. If you are completely
-    new to setuptools, the :ref:`quickstart section <quickstart>` is a good
+    new to setuptools, the :doc:`quickstart section <quickstart>` is a good
     place to start.
 
 ``Setuptools`` provide powerful tools to handle package discovery, including
@@ -97,6 +97,8 @@ in ``src`` that starts with the name ``pkg`` and not ``additional``:
     )
 
 
+.. _Namespace Packages:
+
 Using ``find_namespace:`` or ``find_namespace_packages``
 ========================================================
 ``setuptools``  provides the ``find_namespace:`` (``find_namespace_packages``)

docs/userguide/quickstart.rst

@@ -21,8 +21,7 @@ the backend (build system) it wants to use. The distribution can then
 be generated with whatever tools that provides a ``build sdist``-alike
 functionality. While this may appear cumbersome, given the added pieces,
 it in fact tremendously enhances the portability of your package. The
-change is driven under `PEP 517 <https://www.python.org/dev/peps/pep-0517/#
-build-requirements>``. To learn more about Python packaging in general,
+change is driven under :pep:`517 <517#build-requirements>`. To learn more about Python packaging in general,
 navigate to the `bottom <Resources on python packaging>`_ of this page.
 
 
@@ -122,7 +121,7 @@ keyword in your ``setup.cfg``:
 When this project is installed, a ``main`` script will be installed and will
 invoke the ``some_func`` in the ``__init__.py`` file when called by the user.
 For detailed usage, including managing the additional or optional dependencies,
-go to :ref:`entry_point`.
+go to :doc:`entry_point`.
 
 
 Dependency management
@@ -147,9 +146,11 @@ additional keywords such as ``setup_requires`` that allows you to install
 dependencies before running the script, and ``extras_requires`` that take
 care of those needed by automatically generated scripts. It also provides
 mechanisms to handle dependencies that are not in PyPI. For more advanced use,
-see :ref:`dependency_management`
+see :doc:`dependency_management`
 
 
+.. _Including Data Files:
+
 Including Data Files
 ====================
 The distutils have traditionally allowed installation of "data files", which
@@ -164,7 +165,7 @@ can simply use the ``include_package_data`` keyword:
 
 This tells setuptools to install any data files it finds in your packages.
 The data files must be specified via the distutils' ``MANIFEST.in`` file.
-For more details, see :ref:`datafiles`
+For more details, see :doc:`datafiles`
 
 
 Development mode

setup.cfg

@@ -16,7 +16,7 @@ formats = zip
 
 [metadata]
 name = setuptools
-version = 50.3.0
+version = 50.3.1
 description = Easily download, build, install, upgrade, and uninstall Python packages
 author = Python Packaging Authority
 author_email = distutils-sig@python.org

setuptools/command/build_py.py

@@ -11,7 +11,7 @@ import stat
 
 try:
     from setuptools.lib2to3_ex import Mixin2to3
-except ImportError:
+except Exception:
 
     class Mixin2to3:
         def run_2to3(self, files, doctests=True):

setuptools/command/egg_info.py

@@ -123,12 +123,17 @@ class InfoCommon:
         return safe_name(self.distribution.get_name())
 
     def tagged_version(self):
-        version = self.distribution.get_version()
-        # egg_info may be called more than once for a distribution,
-        # in which case the version string already contains all tags.
-        if self.vtags and version.endswith(self.vtags):
-            return safe_version(version)
-        return safe_version(version + self.vtags)
+        return safe_version(self._maybe_tag(self.distribution.get_version()))
+
+    def _maybe_tag(self, version):
+        """
+        egg_info may be called more than once for a distribution,
+        in which case the version string already contains all tags.
+        """
+        return (
+            version if self.vtags and version.endswith(self.vtags)
+            else version + self.vtags
+        )
 
     def tags(self):
         version = ''

tools/finalize.py

@@ -66,10 +66,11 @@ def check_changes():
     names.
     """
     allowed = 'deprecation', 'breaking', 'change', 'doc', 'misc'
+    except_ = 'README.rst', '.gitignore'
     assert all(
         any(key in file.name for key in allowed)
         for file in pathlib.Path('changelog.d').iterdir()
-        if file.name != '.gitignore'
+        if file.name not in except_
     )
 
 

tox.ini

@@ -49,7 +49,16 @@ extras =
         testing
 changedir = docs
 commands =
-        python -m sphinx . {toxinidir}/build/html
+        {envpython} -m sphinx \
+          -j auto \
+          -b html \
+          --color \
+          -a \
+          -n \
+          -W \
+          -d "{temp_dir}/.doctrees" \
+          . \
+          "{toxinidir}/build/html"
 
 [testenv:finalize]
 skip_install = True