Merge pull request #1765 from venthur/fix/1700

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

changelog.d/1700.change.rst

+Document all supported keywords by migrating the ones from distutils.

docs/keywords.txt

+``name``
+    A string specifying the name of the package.
+
+``version``
+    A string specifying the version number of the package.
+
+``description``
+    A string describing the package in a single line.
+
+``long_description``
+    A string providing a longer description of the package.
+
+``long_description_content_type``
+    A string specifying the content type is used for the ``long_description``
+    (e.g. ``text/markdown``)
+
+``author``
+    A string specifying the author of the package.
+
+``author_email``
+    A string specifying the email address of the package author.
+
+``maintainer``
+    A string specifying the name of the current maintainer, if different from
+    the author. Note that if the maintainer is provided, setuptools will use it
+    as the author in ``PKG-INFO``.
+
+``maintainer_email``
+    A string specifying the email address of the current maintainer, if
+    different from the author.
+
+``url``
+    A string specifying the URL for the package homepage.
+
+``download_url``
+    A string specifying the URL to download the package.
+
+``packages``
+    A list of strings specifying the packages that setuptools will manipulate.
+
+``py_modules``
+    A list of strings specifying the modules that setuptools will manipulate.
+
+``scripts``
+    A list of strings specifying the standalone script files to be built and
+    installed.
+
+``ext_package``
+    A string specifying the base package name for the extensions provided by
+    this package.
+
+``ext_modules``
+    A list of instances of ``setuptools.Extension`` providing the list of
+    Python extensions to be built.
+
+``classifiers``
+    A list of strings describing the categories for the package.
+
+``distclass``
+    A subclass of ``Distribution`` to use.
+
+``script_name``
+    A string specifying the name of the setup.py script -- defaults to
+    ``sys.argv[0]``
+
+``script_args``
+    A list of strings defining the arguments to supply to the setup script.
+
+``options``
+    A dictionary providing the default options for the setup script.
+
+``license``
+    A string specifying the license of the package.
+
+``keywords``
+    A list of strings or a comma-separated string providing descriptive
+    meta-data. See: `PEP 0314`_.
+
+.. _PEP 0314: https://www.python.org/dev/peps/pep-0314/
+
+``platforms``
+    A list of strings or comma-separated string.
+
+``cmdclass``
+    A dictionary providing a mapping of command names to ``Command``
+    subclasses.
+
+``data_files``
+
+    .. warning::
+        ``data_files`` is deprecated. It does not work with wheels, so it
+        should be avoided.
+
+    A list of strings specifying the data files to install.
+
+``package_dir``
+    A dictionary providing a mapping of package to directory names.
+
+``requires``
+
+   .. warning::
+      ``requires`` is superseded by ``install_requires`` and should not be used
+      anymore.
+
+``obsoletes``
+
+   .. warning::
+      ``obsoletes`` is currently ignored by ``pip``.
+
+   List of strings describing packages which this package renders obsolete,
+   meaning that the two projects should not be installed at the same time.
+
+   Version declarations can be supplied. Version numbers must be in the format
+   specified in Version specifiers (e.g. ``foo (<3.0)``).
+
+   This field may be followed by an environment marker after a semicolon (e.g.
+   ``foo; os_name == "posix"``)
+
+   The most common use of this field will be in case a project name changes,
+   e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install
+   Torqued Python, the Gorgon distribution should be removed.
+
+``provides``
+
+   .. warning::
+      ``provides`` is currently ignored by ``pip``.
+
+   List of strings describing package- and virtual package names contained
+   within this package.
+
+   A package may provide additional names, e.g. to indicate that multiple
+   projects have been bundled together. For instance, source distributions of
+   the ZODB project have historically included the transaction project, which
+   is now available as a separate distribution. Installing such a source
+   distribution satisfies requirements for both ZODB and transaction.
+
+   A package may also provide a “virtual” project name, which does not
+   correspond to any separately-distributed project: such a name might be used
+   to indicate an abstract capability which could be supplied by one of
+   multiple projects. E.g., multiple projects might supply RDBMS bindings for
+   use by a given ORM: each project might declare that it provides
+   ORM-bindings, allowing other projects to depend only on having at most one
+   of them installed.
+
+   A version declaration may be supplied and must follow the rules described in
+   Version specifiers. The distribution’s version number will be implied if
+   none is specified (e.g. ``foo (<3.0)``).
+
+   Each package may be followed by an environment marker after a semicolon
+   (e.g. ``foo; os_name == "posix"``).
+
+.. Below are setuptools keywords, above are distutils
+
+``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 on
+    :ref:`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 on :ref:`Including Data Files`.
+
+``package_data``
+    A dictionary mapping package names to lists of glob patterns.  For a
+    complete description and examples, see the section on :ref:`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 on :ref:`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 :ref:`Dynamic
+    Discovery of Services and Plugins` for details and examples of the format
+    of this argument.  In addition, this keyword is used to support
+    :ref:`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 on :ref:`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``
+
+    .. warning::
+        Using ``setup_requires`` is discouraged in favor of `PEP-518`_
+
+    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 (even going so far as to download them using
+    ``EasyInstall``) 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``.)
+
+.. _PEP-518: http://www.python.org/dev/peps/pep-0518/
+
+``dependency_links``
+
+    .. warning::
+        ``dependency_links`` is deprecated. It is not supported anymore by pip.
+
+    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 by tools like EasyInstall to use when installing
+    an ``.egg`` file.
+
+``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 on :ref:`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 :ref:`test` command to run the
+    specified test suite, e.g. via ``setup.py test``.  See the section on the
+    :ref:`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 (even going
+    so far as to download them using ``EasyInstall``).  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 :ref:`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.
+
+``use_2to3_exclude_fixers``
+    List of fixer names to be skipped.
+
+``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.

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