Merge pull request #2438 from webknjaz/bugfixes/distutils-sphinx-refs

Fix refs in distutils sphinx docs

7 files changed, 100 insertions, 53 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 982f5e62..de9fe3f8 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -19,6 +19,7 @@ github_sponsors_url = f'{github_url}/sponsors'
 
 extensions = [
     'sphinx.ext.extlinks',  # allows to create custom roles easily
+    'sphinx.ext.intersphinx',  # allows interlinking external docs sites
     'jaraco.packaging.sphinx',
     'rst.linker',
 ]
@@ -151,7 +152,50 @@ link_files = {
 # Be strict about any broken references:
 nitpicky = True
 
+# Ref: https://stackoverflow.com/a/30624034/595220
+nitpick_ignore = [
+    ('c:func', 'SHGetSpecialFolderPath'),  # ref to MS docs
+    ('envvar', 'DISTUTILS_DEBUG'),  # undocumented
+    ('envvar', 'HOME'),  # undocumented
+    ('envvar', 'PLAT'),  # undocumented
+    ('py:attr', 'CCompiler.language_map'),  # undocumented
+    ('py:attr', 'CCompiler.language_order'),  # undocumented
+    ('py:class', 'distutils.dist.Distribution'),  # undocumented
+    ('py:class', 'distutils.extension.Extension'),  # undocumented
+    ('py:class', 'BorlandCCompiler'),  # undocumented
+    ('py:class', 'CCompiler'),  # undocumented
+    ('py:class', 'CygwinCCompiler'),  # undocumented
+    ('py:class', 'distutils.dist.DistributionMetadata'),  # undocumented
+    ('py:class', 'FileList'),  # undocumented
+    ('py:class', 'IShellLink'),  # ref to MS docs
+    ('py:class', 'MSVCCompiler'),  # undocumented
+    ('py:class', 'OptionDummy'),  # undocumented
+    ('py:class', 'UnixCCompiler'),  # undocumented
+    ('py:exc', 'CompileError'),  # undocumented
+    ('py:exc', 'DistutilsExecError'),  # undocumented
+    ('py:exc', 'DistutilsFileError'),  # undocumented
+    ('py:exc', 'LibError'),  # undocumented
+    ('py:exc', 'LinkError'),  # undocumented
+    ('py:exc', 'PreprocessError'),  # undocumented
+    ('py:func', 'distutils.CCompiler.new_compiler'),  # undocumented
+    # undocumented:
+    ('py:func', 'distutils.dist.DistributionMetadata.read_pkg_file'),
+    ('py:func', 'distutils.file_util._copy_file_contents'),  # undocumented
+    ('py:func', 'distutils.log.debug'),  # undocumented
+    ('py:func', 'distutils.spawn.find_executable'),  # undocumented
+    ('py:func', 'distutils.spawn.spawn'),  # undocumented
+    # TODO: check https://docutils.rtfd.io in the future
+    ('py:mod', 'docutils'),  # there's no Sphinx site documenting this
+]
+
 
 # Ref: https://github.com/python-attrs/attrs/pull/571/files\
 #      #diff-85987f48f1258d9ee486e3191495582dR82
 default_role = 'any'
+
+
+# Allow linking objects on other Sphinx sites seamlessly:
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'python2': ('https://docs.python.org/2', None),
+}
diff --git a/docs/deprecated/distutils/apiref.rst b/docs/deprecated/distutils/apiref.rst
index b14197c2..40a360dd 100644
--- a/docs/deprecated/distutils/apiref.rst
+++ b/docs/deprecated/distutils/apiref.rst
@@ -513,7 +513,7 @@ This module provides the following functions.
    .. method:: CCompiler.detect_language(sources)
 
       Detect the language of a given file, or list of files. Uses the  instance
-      attributes :attr:`language_map` (a dictionary), and  :attr:`language_order` (a
+      attributes :attr:`~CCompiler.language_map` (a dictionary), and  :attr:`~CCompiler.language_order` (a
       list) to do the job.
 
 
@@ -761,7 +761,7 @@ This module provides the following functions.
 
    .. method:: CCompiler.spawn(cmd)
 
-      Invokes :func:`distutils.util.spawn`. This invokes an external  process to run
+      Invokes :func:`distutils.spawn.spawn`. This invokes an external  process to run
       the given command.
 
 
@@ -861,8 +861,8 @@ This module provides :class:`BorlandCCompiler`, a subclass of the abstract
 :class:`CCompiler` class for the Borland C++ compiler.
 
 
-:mod:`distutils.cygwincompiler` --- Cygwin Compiler
-===================================================
+:mod:`distutils.cygwinccompiler` --- Cygwin Compiler
+====================================================
 
 .. module:: distutils.cygwinccompiler
 
@@ -1017,7 +1017,7 @@ directories.
    directories.  If *preserve_symlinks* is true, symlinks will be copied as
    symlinks (on platforms that support them!); otherwise (the default), the
    destination of the symlink will be copied.  *update* and *verbose* are the same
-   as for :func:`copy_file`.
+   as for :func:`~distutils.file_util.copy_file`.
 
    Files in *src* that begin with :file:`.nfs` are skipped (more information on
    these files is available in answer D2 of the `NFS FAQ page
@@ -1058,7 +1058,7 @@ This module contains some utility functions for operating on individual files.
    (using :func:`os.symlink`) instead of copying: set it to ``'hard'`` or
    ``'sym'``; if it is ``None`` (the default), files are copied. Don't set *link*
    on systems that don't support it: :func:`copy_file` doesn't check if hard or
-   symbolic linking is available.  It uses :func:`_copy_file_contents` to copy file
+   symbolic linking is available.  It uses :func:`~distutils.file_util._copy_file_contents` to copy file
    contents.
 
    Return a tuple ``(dest_name, copied)``: *dest_name* is the actual  name of the
@@ -1304,8 +1304,8 @@ represents the module distribution being built/installed/distributed.
               scripts
 
 
-This module provides the :class:`Extension` class, used to describe C/C++
-extension modules in setup scripts.
+This module provides the :class:`~distutils.extension.Extension` class,
+used to describe C/C++ extension modules in setup scripts.
 
 .. % \subsection{Ungrouped modules}
 .. % The following haven't been moved into a more appropriate section yet.
@@ -1363,7 +1363,7 @@ provides the following additional features:
    help_string)`` 3-tuples as described in the constructor for
    :class:`FancyGetopt`. *negative_opt* should be a dictionary mapping option names
    to option names, both the key and value should be in the *options* list.
-   *object* is an object which will be used to store values (see the :meth:`getopt`
+   *object* is an object which will be used to store values (see the :meth:`~FancyGetopt.getopt`
    method of the :class:`FancyGetopt` class). *args* is the argument list. Will use
    ``sys.argv[1:]`` if you  pass ``None`` as *args*.
 
@@ -1441,9 +1441,10 @@ filesystem and building lists of files.
    :synopsis: Provides the spawn() function
 
 
-This module provides the :func:`spawn` function, a front-end to  various
-platform-specific functions for launching another program in a  sub-process.
-Also provides :func:`find_executable` to search the path for a given executable
+This module provides the :func:`~distutils.spawn.spawn` function, a
+front-end to  various platform-specific functions for launching another
+program in a  sub-process.
+Also provides :func:`~distutils.spawn.find_executable` to search the path for a given executable
 name.
 
 
@@ -1755,7 +1756,7 @@ implementing.  This module should implement a class with the same name as the
 module (and the command).  So, for instance, to create the command
 ``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy
 :file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit
-it so that it's implementing the class :class:`peel_banana`, a subclass of
+it so that it's implementing the class ``peel_banana``, a subclass of
 :class:`distutils.cmd.Command`.
 
 Subclasses of :class:`Command` must define the following methods.
@@ -2065,6 +2066,6 @@ This is described in more detail in :pep:`301`.
 
 The ``check`` command performs some tests on the meta-data of a package.
 For example, it verifies that all required meta-data are provided as
-the arguments passed to the :func:`setup` function.
+the arguments passed to the :func:`~distutils.core.setup` function.
 
 .. % todo
diff --git a/docs/deprecated/distutils/configfile.rst b/docs/deprecated/distutils/configfile.rst
index 2a5c8329..328936fb 100644
--- a/docs/deprecated/distutils/configfile.rst
+++ b/docs/deprecated/distutils/configfile.rst
@@ -78,9 +78,9 @@ Note that an option spelled :option:`!--foo-bar` on the command-line  is spelled
 .. _distutils-build-ext-inplace:
 
 For example, say you want your extensions to be built "in-place"---that is, you
-have an extension :mod:`pkg.ext`, and you want the compiled extension file
+have an extension ``pkg.ext``, and you want the compiled extension file
 (:file:`ext.so` on Unix, say) to be put in the same source directory as your
-pure Python modules :mod:`pkg.mod1` and :mod:`pkg.mod2`.  You can always use the
+pure Python modules ``pkg.mod1`` and ``pkg.mod2``.  You can always use the
 :option:`!--inplace` option on the command-line to ensure this:
 
 .. code-block:: sh
diff --git a/docs/deprecated/distutils/examples.rst b/docs/deprecated/distutils/examples.rst
index e492b7f6..d0984655 100644
--- a/docs/deprecated/distutils/examples.rst
+++ b/docs/deprecated/distutils/examples.rst
@@ -49,7 +49,7 @@ convention to follow).  However, the distribution name is used to generate
 filenames, so you should stick to letters, digits, underscores, and hyphens.
 
 Since ``py_modules`` is a list, you can of course specify multiple
-modules, eg. if you're distributing modules :mod:`foo` and :mod:`bar`, your
+modules, eg. if you're distributing modules ``foo`` and ``bar``, your
 setup might look like this::
 
    <root>/
@@ -111,8 +111,8 @@ Distutils where source files in the root package live::
          )
 
 More typically, though, you will want to distribute multiple modules in the same
-package (or in sub-packages).  For example, if the :mod:`foo`  and :mod:`bar`
-modules belong in package :mod:`foobar`, one way to layout your source tree is
+package (or in sub-packages).  For example, if the ``foo``  and ``bar``
+modules belong in package ``foobar``, one way to layout your source tree is
 ::
 
    <root>/
@@ -133,7 +133,7 @@ requires the least work to describe in your setup script::
 
 If you want to put modules in directories not named for their package, then you
 need to use the ``package_dir`` option again.  For example, if the
-:file:`src` directory holds modules in the :mod:`foobar` package::
+:file:`src` directory holds modules in the ``foobar`` package::
 
    <root>/
            setup.py
@@ -210,7 +210,7 @@ single extension module in a single C source file, is::
            setup.py
            foo.c
 
-If the :mod:`foo` extension belongs in the root package, the setup script for
+If the ``foo`` extension belongs in the root package, the setup script for
 this could be  ::
 
    from distutils.core import setup
@@ -220,10 +220,10 @@ this could be  ::
          ext_modules=[Extension('foo', ['foo.c'])],
          )
 
-If the extension actually belongs in a package, say :mod:`foopkg`, then
+If the extension actually belongs in a package, say ``foopkg``, then
 
 With exactly the same source tree layout, this extension can be put in the
-:mod:`foopkg` package simply by changing the name of the extension::
+``foopkg`` package simply by changing the name of the extension::
 
    from distutils.core import setup
    from distutils.extension import Extension
@@ -311,7 +311,7 @@ in the Metadata, and ``pyX.X`` the major and minor version of Python like
 
 You can read back this static file, by using the
 :class:`distutils.dist.DistributionMetadata` class and its
-:func:`read_pkg_file` method::
+:func:`~distutils.dist.DistributionMetadata.read_pkg_file` method::
 
     >>> from distutils.dist import DistributionMetadata
     >>> metadata = DistributionMetadata()
diff --git a/docs/deprecated/distutils/extending.rst b/docs/deprecated/distutils/extending.rst
index 1075e817..c99d3c79 100644
--- a/docs/deprecated/distutils/extending.rst
+++ b/docs/deprecated/distutils/extending.rst
@@ -19,9 +19,9 @@ convenience.
 
 Most distutils command implementations are subclasses of the
 :class:`distutils.cmd.Command` class.  New commands may directly inherit from
-:class:`Command`, while replacements often derive from :class:`Command`
+:class:`~distutils.cmd.Command`, while replacements often derive from :class:`~distutils.cmd.Command`
 indirectly, directly subclassing the command they are replacing.  Commands are
-required to derive from :class:`Command`.
+required to derive from :class:`~distutils.cmd.Command`.
 
 .. % \section{Extending existing commands}
 .. % \label{extend-existing}
@@ -78,12 +78,12 @@ packages searched for command implementations; multiple package names should be
 separated by commas.  When not specified, the search is only performed in the
 :mod:`distutils.command` package.  When :file:`setup.py` is run with the option
 ``--command-packages distcmds,buildcmds``, however, the packages
-:mod:`distutils.command`, :mod:`distcmds`, and :mod:`buildcmds` will be searched
+:mod:`distutils.command`, ``distcmds``, and ``buildcmds`` will be searched
 in that order.  New commands are expected to be implemented in modules of the
 same name as the command by classes sharing the same name.  Given the example
 command line option above, the command :command:`bdist_openpkg` could be
-implemented by the class :class:`distcmds.bdist_openpkg.bdist_openpkg` or
-:class:`buildcmds.bdist_openpkg.bdist_openpkg`.
+implemented by the class ``distcmds.bdist_openpkg.bdist_openpkg`` or
+``buildcmds.bdist_openpkg.bdist_openpkg``.
 
 
 Adding new distribution types
diff --git a/docs/deprecated/distutils/introduction.rst b/docs/deprecated/distutils/introduction.rst
index 1f8a560e..7491b965 100644
--- a/docs/deprecated/distutils/introduction.rst
+++ b/docs/deprecated/distutils/introduction.rst
@@ -55,7 +55,7 @@ Unlike, say, Autoconf-style configure scripts, the setup script may be run
 multiple times in the course of building and installing your module
 distribution.
 
-If all you want to do is distribute a module called :mod:`foo`, contained in a
+If all you want to do is distribute a module called ``foo``, contained in a
 file :file:`foo.py`, then your setup script can be as simple as this::
 
    from distutils.core import setup
@@ -67,7 +67,7 @@ file :file:`foo.py`, then your setup script can be as simple as this::
 Some observations:
 
 * most information that you supply to the Distutils is supplied as keyword
-  arguments to the :func:`setup` function
+  arguments to the :func:`~distutils.core.setup` function
 
 * those keyword arguments fall into two categories: package metadata (name,
   version number) and information about what's in the package (a list of pure
@@ -96,7 +96,7 @@ containing your setup script :file:`setup.py`, and your module :file:`foo.py`.
 The archive file will be named :file:`foo-1.0.tar.gz` (or :file:`.zip`), and
 will unpack into a directory :file:`foo-1.0`.
 
-If an end-user wishes to install your :mod:`foo` module, all they have to do is
+If an end-user wishes to install your ``foo`` module, all they have to do is
 download :file:`foo-1.0.tar.gz` (or :file:`.zip`), unpack it, and---from the
 :file:`foo-1.0` directory---run ::
 
diff --git a/docs/deprecated/distutils/setupscript.rst b/docs/deprecated/distutils/setupscript.rst
index 4386a60b..f49c4f89 100644
--- a/docs/deprecated/distutils/setupscript.rst
+++ b/docs/deprecated/distutils/setupscript.rst
@@ -10,9 +10,9 @@ The setup script is the centre of all activity in building, distributing, and
 installing modules using the Distutils.  The main purpose of the setup script is
 to describe your module distribution to the Distutils, so that the various
 commands that operate on your modules do the right thing.  As we saw in section
-:ref:`distutils-simple-example` above, the setup script consists mainly of a call to
-:func:`setup`, and most information supplied to the Distutils by the module
-developer is supplied as keyword arguments to :func:`setup`.
+:ref:`distutils-simple-example` above, the setup script consists mainly of a call to :func:`~distutils.core.setup`, and most information
+supplied to the Distutils by the module developer is supplied as keyword
+arguments to :func:`~distutils.core.setup`.
 
 Here's a slightly more involved example, which we'll follow for the next couple
 of sections: the Distutils' own setup script.  (Keep in mind that although the
@@ -80,7 +80,7 @@ If you use a different convention to lay out your source directory, that's no
 problem: you just have to supply the ``package_dir`` option to tell the
 Distutils about your convention.  For example, say you keep all Python source
 under :file:`lib`, so that modules in the "root package" (i.e., not in any
-package at all) are in :file:`lib`, modules in the :mod:`foo` package are in
+package at all) are in :file:`lib`, modules in the ``foo`` package are in
 :file:`lib/foo`, and so forth.  Then you would put ::
 
     package_dir = {'': 'lib'}
@@ -90,14 +90,14 @@ empty package name stands for the root package.  The values are directory names
 relative to your distribution root.  In this case, when you say ``packages =
 ['foo']``, you are promising that the file :file:`lib/foo/__init__.py` exists.
 
-Another possible convention is to put the :mod:`foo` package right in
-:file:`lib`, the :mod:`foo.bar` package in :file:`lib/bar`, etc.  This would be
+Another possible convention is to put the ``foo`` package right in
+:file:`lib`, the ``foo.bar`` package in :file:`lib/bar`, etc.  This would be
 written in the setup script as ::
 
     package_dir = {'foo': 'lib'}
 
 A ``package: dir`` entry in the ``package_dir`` dictionary implicitly
-applies to all packages below *package*, so the :mod:`foo.bar` case is
+applies to all packages below *package*, so the ``foo.bar`` case is
 automatically handled here.  In this example, having ``packages = ['foo',
 'foo.bar']`` tells the Distutils to look for :file:`lib/__init__.py` and
 :file:`lib/bar/__init__.py`.  (Keep in mind that although ``package_dir``
@@ -119,7 +119,7 @@ section :ref:`distutils-simple-example`; here is a slightly more involved exampl
     py_modules = ['mod1', 'pkg.mod2']
 
 This describes two modules, one of them in the "root" package, the other in the
-:mod:`pkg` package.  Again, the default package/directory layout implies that
+``pkg`` package.  Again, the default package/directory layout implies that
 these two modules can be found in :file:`mod1.py` and :file:`pkg/mod2.py`, and
 that :file:`pkg/__init__.py` exists as well. And again, you can override the
 package/directory correspondence using the ``package_dir`` option.
@@ -139,18 +139,19 @@ directories, libraries to link with, etc.).
 
 .. XXX read over this section
 
-All of this is done through another keyword argument to :func:`setup`, the
+All of this is done through another keyword argument to
+:func:`~distutils.core.setup`, the
 ``ext_modules`` option.  ``ext_modules`` is just a list of
 :class:`~distutils.core.Extension` instances, each of which describes a
 single extension module.
-Suppose your distribution includes a single extension, called :mod:`foo` and
+Suppose your distribution includes a single extension, called ``foo`` and
 implemented by :file:`foo.c`.  If no additional instructions to the
 compiler/linker are needed, describing this extension is quite simple::
 
     Extension('foo', ['foo.c'])
 
-The :class:`Extension` class can be imported from :mod:`distutils.core` along
-with :func:`setup`.  Thus, the setup script for a module distribution that
+The :class:`~distutils.extension.Extension` class can be imported from :mod:`distutils.core` along
+with :func:`~distutils.core.setup`.  Thus, the setup script for a module distribution that
 contains only this one extension and nothing else might be::
 
     from distutils.core import setup, Extension
@@ -159,7 +160,7 @@ contains only this one extension and nothing else might be::
           ext_modules=[Extension('foo', ['foo.c'])],
           )
 
-The :class:`Extension` class (actually, the underlying extension-building
+The :class:`~distutils.extension.Extension` class (actually, the underlying extension-building
 machinery implemented by the :command:`build_ext` command) supports a great deal
 of flexibility in describing Python extensions, which is explained in the
 following sections.
@@ -177,14 +178,14 @@ describes an extension that lives in the root package, while ::
 
     Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])
 
-describes the same extension in the :mod:`pkg` package.  The source files and
+describes the same extension in the ``pkg`` package.  The source files and
 resulting object code are identical in both cases; the only difference is where
 in the filesystem (and therefore where in Python's namespace hierarchy) the
 resulting extension lives.
 
 If you have a number of extensions all in the same package (or all under the
 same base package), use the ``ext_package`` keyword argument to
-:func:`setup`.  For example, ::
+:func:`~distutils.core.setup`.  For example, ::
 
     setup(...,
           ext_package='pkg',
@@ -192,8 +193,8 @@ same base package), use the ``ext_package`` keyword argument to
                        Extension('subpkg.bar', ['bar.c'])],
          )
 
-will compile :file:`foo.c` to the extension :mod:`pkg.foo`, and :file:`bar.c` to
-:mod:`pkg.subpkg.bar`.
+will compile :file:`foo.c` to the extension ``pkg.foo``, and
+:file:`bar.c` to ``pkg.subpkg.bar``.
 
 
 Extension source files
@@ -375,7 +376,8 @@ These relationships can be specified using keyword arguments to the
 :func:`distutils.core.setup` function.
 
 Dependencies on other Python modules and packages can be specified by supplying
-the *requires* keyword argument to :func:`setup`. The value must be a list of
+the *requires* keyword argument to :func:`~distutils.core.setup`. The
+value must be a list of
 strings.  Each string specifies a package that is required, and optionally what
 versions are sufficient.
 
@@ -407,7 +409,7 @@ Let's look at a bunch of examples:
 
 Now that we can specify dependencies, we also need to be able to specify what we
 provide that other distributions can require.  This is done using the *provides*
-keyword argument to :func:`setup`. The value for this keyword is a list of
+keyword argument to :func:`~distutils.core.setup`. The value for this keyword is a list of
 strings, each of which names a Python module or package, and optionally
 identifies the version.  If the version is not specified, it is assumed to match
 that of the distribution.
@@ -474,7 +476,7 @@ containing documentation that might be of interest to programmers using the
 package.  These files are called :dfn:`package data`.
 
 Package data can be added to packages using the ``package_data`` keyword
-argument to the :func:`setup` function.  The value must be a mapping from
+argument to the :func:`~distutils.core.setup` function.  The value must be a mapping from
 package name to a list of relative path names that should be copied into the
 package.  The paths are interpreted as relative to the directory containing the
 package (information from the ``package_dir`` mapping is used if appropriate);
@@ -497,7 +499,7 @@ the files can be arranged like this in the source tree::
                 spoons.dat
                 forks.dat
 
-The corresponding call to :func:`setup` might be::
+The corresponding call to :func:`~distutils.core.setup` might be::
 
     setup(...,
           packages=['mypkg'],