diff --git a/docs/conf.py b/docs/conf.py index 982f5e6212..de9fe3f892 100644 --- a/docs/conf.py +++ b/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), +} diff --git a/docs/deprecated/distutils/apiref.rst b/docs/deprecated/distutils/apiref.rst index b14197c2f9..40a360ddf2 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 2a5c8329e3..328936fb40 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 e492b7f605..d0984655df 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:: / @@ -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 :: / @@ -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:: / 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 1075e81779..c99d3c791f 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 1f8a560e13..7491b965a5 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 4386a60b66..f49c4f893f 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'],