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

Fix refs in distutils sphinx docs

docs/conf.py

@@ -19,6 +19,7 @@
 
 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 @@
 # 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),
+}

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

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

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()

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

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 ::