Merge pull request #2657 from pypa/feature/distutils-docs

Feature/distutils docs

docs/conf.py

@@ -99,3 +99,47 @@
 
 # Add support for inline tabs
 extensions += ['sphinx_inline_tabs']
+
+# Support for distutils
+
+# 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
+]
+
+# 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/_setuptools_disclaimer.rst

@@ -0,0 +1,5 @@
+.. note::
+
+   This document is being retained solely until the ``setuptools`` documentation
+   at https://setuptools.readthedocs.io/en/latest/setuptools.html
+   independently covers all of the relevant information currently included here.

docs/deprecated/distutils/commandref.rst

@@ -0,0 +1,106 @@
+.. _reference:
+
+*****************
+Command Reference
+*****************
+
+.. include:: ./_setuptools_disclaimer.rst
+
+.. % \section{Building modules: the \protect\command{build} command family}
+.. % \label{build-cmds}
+.. % \subsubsection{\protect\command{build}}
+.. % \label{build-cmd}
+.. % \subsubsection{\protect\command{build\_py}}
+.. % \label{build-py-cmd}
+.. % \subsubsection{\protect\command{build\_ext}}
+.. % \label{build-ext-cmd}
+.. % \subsubsection{\protect\command{build\_clib}}
+.. % \label{build-clib-cmd}
+
+
+.. _install-cmd:
+
+Installing modules: the :command:`install` command family
+=========================================================
+
+The install command ensures that the build commands have been run and then runs
+the subcommands :command:`install_lib`, :command:`install_data` and
+:command:`install_scripts`.
+
+.. % \subsubsection{\protect\command{install\_lib}}
+.. % \label{install-lib-cmd}
+
+
+.. _install-data-cmd:
+
+:command:`install_data`
+-----------------------
+
+This command installs all data files provided with the distribution.
+
+
+.. _install-scripts-cmd:
+
+:command:`install_scripts`
+--------------------------
+
+This command installs all (Python) scripts in the distribution.
+
+.. % \subsection{Cleaning up: the \protect\command{clean} command}
+.. % \label{clean-cmd}
+
+
+.. _sdist-cmd:
+
+Creating a source distribution: the :command:`sdist` command
+============================================================
+
+.. XXX fragment moved down from above: needs context!
+
+The manifest template commands are:
+
++-------------------------------------------+-----------------------------------------------+
+| Command                                   | Description                                   |
++===========================================+===============================================+
+| :command:`include pat1 pat2 ...`          | include all files matching any of the listed  |
+|                                           | patterns                                      |
++-------------------------------------------+-----------------------------------------------+
+| :command:`exclude pat1 pat2 ...`          | exclude all files matching any of the listed  |
+|                                           | patterns                                      |
++-------------------------------------------+-----------------------------------------------+
+| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of |
+| ...`                                      | the listed patterns                           |
++-------------------------------------------+-----------------------------------------------+
+| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of |
+| ...`                                      | the listed patterns                           |
++-------------------------------------------+-----------------------------------------------+
+| :command:`global-include pat1 pat2 ...`   | include all files anywhere in the source tree |
+|                                           | matching --- & any of the listed patterns     |
++-------------------------------------------+-----------------------------------------------+
+| :command:`global-exclude pat1 pat2 ...`   | exclude all files anywhere in the source tree |
+|                                           | matching --- & any of the listed patterns     |
++-------------------------------------------+-----------------------------------------------+
+| :command:`prune dir`                      | exclude all files under *dir*                 |
++-------------------------------------------+-----------------------------------------------+
+| :command:`graft dir`                      | include all files under *dir*                 |
++-------------------------------------------+-----------------------------------------------+
+
+The patterns here are Unix-style "glob" patterns: ``*`` matches any sequence of
+regular filename characters, ``?`` matches any single regular filename
+character, and ``[range]`` matches any of the characters in *range* (e.g.,
+``a-z``, ``a-zA-Z``, ``a-f0-9_.``).  The definition of "regular filename
+character" is platform-specific: on Unix it is anything except slash; on Windows
+anything except backslash or colon.
+
+.. XXX Windows support not there yet
+
+.. % \section{Creating a built distribution: the
+.. % \protect\command{bdist} command family}
+.. % \label{bdist-cmds}
+
+.. % \subsection{\protect\command{bdist}}
+.. % \subsection{\protect\command{bdist\_dumb}}
+.. % \subsection{\protect\command{bdist\_rpm}}
+.. % \subsection{\protect\command{bdist\_wininst}}
+
+

docs/deprecated/distutils/configfile.rst

@@ -0,0 +1,144 @@
+.. _setup-config:
+
+************************************
+Writing the Setup Configuration File
+************************************
+
+.. include:: ./_setuptools_disclaimer.rst
+
+Often, it's not possible to write down everything needed to build a distribution
+*a priori*: you may need to get some information from the user, or from the
+user's system, in order to proceed.  As long as that information is fairly
+simple---a list of directories to search for C header files or libraries, for
+example---then providing a configuration file, :file:`setup.cfg`, for users to
+edit is a cheap and easy way to solicit it.  Configuration files also let you
+provide default values for any command option, which the installer can then
+override either on the command-line or by editing the config file.
+
+The setup configuration file is a useful middle-ground between the setup
+script---which, ideally, would be opaque to installers [#]_---and the command-line to
+the setup script, which is outside of your control and entirely up to the
+installer.  In fact, :file:`setup.cfg` (and any other Distutils configuration
+files present on the target system) are processed after the contents of the
+setup script, but before the command-line.  This has  several useful
+consequences:
+
+.. % (If you have more advanced needs, such as determining which extensions
+.. % to build based on what capabilities are present on the target system,
+.. % then you need the Distutils ``auto-configuration'' facility.  This
+.. % started to appear in Distutils 0.9 but, as of this writing, isn't mature
+.. % or stable enough yet for real-world use.)
+
+* installers can override some of what you put in :file:`setup.py` by editing
+  :file:`setup.cfg`
+
+* you can provide non-standard defaults for options that are not easily set in
+  :file:`setup.py`
+
+* installers can override anything in :file:`setup.cfg` using the command-line
+  options to :file:`setup.py`
+
+The basic syntax of the configuration file is simple:
+
+.. code-block:: ini
+
+   [command]
+   option=value
+   ...
+
+where *command* is one of the Distutils commands (e.g. :command:`build_py`,
+:command:`install`), and *option* is one of the options that command supports.
+Any number of options can be supplied for each command, and any number of
+command sections can be included in the file.  Blank lines are ignored, as are
+comments, which run from a ``'#'`` character until the end of the line.  Long
+option values can be split across multiple lines simply by indenting the
+continuation lines.
+
+You can find out the list of options supported by a particular command with the
+universal :option:`!--help` option, e.g.
+
+.. code-block:: shell-session
+
+   $ python setup.py --help build_ext
+   [...]
+   Options for 'build_ext' command:
+     --build-lib (-b)     directory for compiled extension modules
+     --build-temp (-t)    directory for temporary files (build by-products)
+     --inplace (-i)       ignore build-lib and put compiled extensions into the
+                          source directory alongside your pure Python modules
+     --include-dirs (-I)  list of directories to search for header files
+     --define (-D)        C preprocessor macros to define
+     --undef (-U)         C preprocessor macros to undefine
+     --swig-opts          list of SWIG command line options
+   [...]
+
+Note that an option spelled :option:`!--foo-bar` on the command-line  is spelled
+``foo_bar`` in configuration files.
+
+.. _distutils-build-ext-inplace:
+
+For example, say you want your extensions to be built "in-place"---that is, you
+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 ``pkg.mod1`` and ``pkg.mod2``.  You can always use the
+:option:`!--inplace` option on the command-line to ensure this:
+
+.. code-block:: sh
+
+   python setup.py build_ext --inplace
+
+But this requires that you always specify the :command:`build_ext` command
+explicitly, and remember to provide :option:`!--inplace`. An easier way is to
+"set and forget" this option, by encoding it in :file:`setup.cfg`, the
+configuration file for this distribution:
+
+.. code-block:: ini
+
+   [build_ext]
+   inplace=1
+
+This will affect all builds of this module distribution, whether or not you
+explicitly specify :command:`build_ext`.  If you include :file:`setup.cfg` in
+your source distribution, it will also affect end-user builds---which is
+probably a bad idea for this option, since always building extensions in-place
+would break installation of the module distribution.  In certain peculiar cases,
+though, modules are built right in their installation directory, so this is
+conceivably a useful ability.  (Distributing extensions that expect to be built
+in their installation directory is almost always a bad idea, though.)
+
+Another example: certain commands take a lot of options that don't change from
+run to run; for example, :command:`bdist_rpm` needs to know everything required
+to generate a "spec" file for creating an RPM distribution.  Some of this
+information comes from the setup script, and some is automatically generated by
+the Distutils (such as the list of files installed).  But some of it has to be
+supplied as options to :command:`bdist_rpm`, which would be very tedious to do
+on the command-line for every run.  Hence, here is a snippet from the Distutils'
+own :file:`setup.cfg`:
+
+.. code-block:: ini
+
+   [bdist_rpm]
+   release = 1
+   packager = Greg Ward <gward@python.net>
+   doc_files = CHANGES.txt
+               README.txt
+               USAGE.txt
+               doc/
+               examples/
+
+Note that the ``doc_files`` option is simply a whitespace-separated string
+split across multiple lines for readability.
+
+
+.. seealso::
+
+   :ref:`inst-config-syntax` in "Installing Python Modules"
+      More information on the configuration files is available in the manual for
+      system administrators.
+
+
+.. rubric:: Footnotes
+
+.. [#] This ideal probably won't be achieved until auto-configuration is fully
+   supported by the Distutils.
+