Merge pull request #2427 from webknjaz/maintenance/resurrect-docs-interlinking

Resurrect docs interlinking

changelog.d/2427.doc.rst

+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 @@ 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/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
 =============================
@@ -266,7 +267,7 @@ the two dependencies ``PDF`` maps to.
 
 The second use case is that other package can use this "extra" for their
 own dependencies. For example, if "Project-B" needs "project A" with PDF support
-installed, it might declare the dependency like this::
+installed, it might declare the dependency like this:
 
 .. code-block:: ini
 
@@ -309,4 +310,4 @@ In some cases, you might need to specify the minimum required python version.
 This is handled with the ``python_requires`` keyword supplied to ``setup.cfg``
 or ``setup.py``.
 
-Example WIP
\ No newline at end of file
+Example WIP

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

@@ -33,6 +33,8 @@ with ``__init__.py`` as:
 
 and ``__main__.py`` providing a hook:
 
+.. code-block:: python
+
     from . import hello_world
     if __name__ == '__main__':
         hello_world()
@@ -49,7 +51,7 @@ user-friendly name for installers of the package to execute. Installers
 like pip will create wrapper scripts to execute a function. In the
 above example, to create a command ``hello-world`` that invokes
 ``timmins.hello_world``, add a console script entry point to
-``setup.cfg``::
+``setup.cfg``:
 
 .. code-block:: ini
 
@@ -74,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
 ====================
 
@@ -138,9 +142,9 @@ 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::
+above example:
 
 .. code-block:: ini
 

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.
 
 
@@ -82,8 +81,8 @@ Automatic package discovery
 For simple projects, it's usually easy enough to manually add packages to
 the ``packages`` keyword in ``setup.cfg``.  However, for very large projects
 , it can be a big burden to keep the package list updated. ``setuptools``
-therefore provides two convenient tools to ease the burden: ``find: `` and
-``find_namespace: ``. To use it in your project:
+therefore provides two convenient tools to ease the burden: :literal:`find:\ ` and
+:literal:`find_namespace:\ `. To use it in your project:
 
 .. code-block:: ini
 
@@ -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

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