Merge pull request #1765 from venthur/fix/1700

Moved distutils' doc for setup-keywords into our doc to document all supported keywords

1 files changed, 10 insertions, 169 deletions

diff --git a/docs/setuptools.txt b/docs/setuptools.txt
index c37b7ec5..7e0914b7 100644
--- a/docs/setuptools.txt
+++ b/docs/setuptools.txt
@@ -229,174 +229,7 @@ The following keyword arguments to ``setup()`` are added or changed by
 ``setuptools``.  All of them are optional; you do not have to supply them
 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`_.
-
-``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`_.
-
-``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
-    ``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
-    source distribution.)
-
-``zip_safe``
-    A boolean (True or False) flag specifying whether the project can be
-    safely installed and run from a zip file.  If this argument is not
-    supplied, the ``bdist_egg`` command will have to analyze all of your
-    project's contents for possible problems each time it builds an egg.
-
-``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.
-
-``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`_.
-
-``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.
-
-``python_requires``
-    A string corresponding to a version specifier (as defined in PEP 440) for
-    the Python version, used to specify the Requires-Python defined in PEP 345.
-
-``setup_requires``
-    A string or list of strings specifying what other distributions need to
-    be present in order for the *setup script* to run.  ``setuptools`` will
-    attempt to obtain these (using pip if available) before processing the
-    rest of the setup script or commands.  This argument is needed if you
-    are using distutils extensions as part of your build process; for
-    example, extensions that process setup() arguments and turn them into
-    EGG-INFO metadata files.
-
-    (Note: projects listed in ``setup_requires`` will NOT be automatically
-    installed on the system where the setup script is being run.  They are
-    simply downloaded to the ./.eggs directory if they're not locally available
-    already.  If you want them to be installed, as well as being available
-    when the setup script is run, you should add them to ``install_requires``
-    **and** ``setup_requires``.)
-
-``dependency_links``
-    A list of strings naming URLs to be searched when satisfying dependencies.
-    These links will be used if needed to install packages specified by
-    ``setup_requires`` or ``tests_require``.  They will also be written into
-    the egg's metadata for use during install by tools that support them.
-
-``namespace_packages``
-    A list of strings naming the project's "namespace packages".  A namespace
-    package is a package that may be split across multiple project
-    distributions.  For example, Zope 3's ``zope`` package is a namespace
-    package, because subpackages like ``zope.interface`` and ``zope.publisher``
-    may be distributed separately.  The egg runtime system can automatically
-    merge such subpackages into a single parent package at runtime, as long
-    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.
-
-``test_suite``
-    A string naming a ``unittest.TestCase`` subclass (or a package or module
-    containing one or more of them, or a method of such a subclass), or naming
-    a function that can be called with no arguments and returns a
-    ``unittest.TestSuite``.  If the named suite is a module, and the module
-    has an ``additional_tests()`` function, it is called and the results are
-    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
-    specified test suite, e.g. via ``setup.py test``.  See the section on the
-    `test`_ command below for more details.
-
-    New in 41.5.0: Deprecated the test command.
-
-``tests_require``
-    If your project's tests need one or more additional packages besides those
-    needed to install it, you can use this option to specify them.  It should
-    be a string or list of strings specifying what other distributions need to
-    be present for the package's tests to run.  When you run the ``test``
-    command, ``setuptools`` will  attempt to obtain these (using pip if
-    available).  Note that these required projects will *not* be installed on
-    the system where the tests are run, but only downloaded to the project's setup
-    directory if they're not already installed locally.
-
-    New in 41.5.0: Deprecated the test command.
-
-.. _test_loader:
-
-``test_loader``
-    If you would like to use a different way of finding tests to run than what
-    setuptools normally uses, you can specify a module name and class name in
-    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
-    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.
-
-    The module name and class name must be separated by a ``:``.  The default
-    value of this argument is ``"setuptools.command.test:ScanningLoader"``.  If
-    you want to use the default ``unittest`` behavior, you can specify
-    ``"unittest:TestLoader"`` as your ``test_loader`` argument instead.  This
-    will prevent automatic scanning of submodules and subpackages.
-
-    The module and class you specify here may be contained in another package,
-    as long as you use the ``tests_require`` option to ensure that the package
-    containing the loader class is available when the ``test`` command is run.
-
-    New in 41.5.0: Deprecated the test command.
-
-``eager_resources``
-    A list of strings naming resources that should be extracted together, if
-    any of them is needed, or if any C extensions included in the project are
-    imported.  This argument is only useful if the project will be installed as
-    a zipfile, and there is a need to have all of the listed resources be
-    extracted to the filesystem *as a unit*.  Resources listed here
-    should be "/"-separated paths, relative to the source root, so to list a
-    resource ``foo.png`` in package ``bar.baz``, you would include the string
-    ``bar/baz/foo.png`` in this argument.
-
-    If you only need to obtain resources one at a time, or you don't have any C
-    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`_.
-
-``use_2to3``
-    Convert the source code from Python 2 to Python 3 with 2to3 during the
-    build process. See :doc:`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.
-
-``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.
-
-``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.
+.. include:: keywords.txt
 
 
 Using ``find_packages()``
@@ -505,6 +338,8 @@ With this layout, the package directory is specified as ``src``, as such::
 
 .. _PEP 420: https://www.python.org/dev/peps/pep-0420/
 
+.. _Automatic Script Creation:
+
 Automatic Script Creation
 =========================
 
@@ -591,6 +426,7 @@ and version is in use.  The header script will check this and exit with an
 error if the ``.egg`` file has been renamed or is invoked via a symlink that
 changes its base name.
 
+.. _Declaring Dependencies:
 
 Declaring Dependencies
 ======================
@@ -846,6 +682,8 @@ detailed in `PEP 508`_.
 
 .. _PEP 508: https://www.python.org/dev/peps/pep-0508/
 
+.. _Including Data Files:
+
 Including Data Files
 ====================
 
@@ -1021,6 +859,7 @@ 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.
 
+.. _Automatic Resource Extraction:
 
 Automatic Resource Extraction
 -----------------------------
@@ -1066,6 +905,8 @@ Extensible Applications and Frameworks
 
 .. _Entry Points:
 
+.. _Dynamic Discovery of Services and Plugins:
+
 Dynamic Discovery of Services and Plugins
 -----------------------------------------
 
@@ -2054,7 +1895,7 @@ result (which must be a ``unittest.TestSuite``) is 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.  (Note: if your project specifies
 a ``test_loader``, the rules for processing the chosen ``test_suite`` may
-differ; see the `test_loader`_ documentation for more details.)
+differ; see the :ref:`test_loader <test_loader>` documentation for more details.)
 
 Note that many test systems including ``doctest`` support wrapping their
 non-``unittest`` tests in ``TestSuite`` objects.  So, if you are using a test