Docs update.

1 files changed, 185 insertions, 0 deletions

diff --git a/docs/setuptools.txt b/docs/setuptools.txt
index 5ce2c7b1..77de255b 100644
--- a/docs/setuptools.txt
+++ b/docs/setuptools.txt
@@ -2398,6 +2398,191 @@ The ``upload_docs`` command has the following options:
     https://pypi.python.org/pypi (i.e., the main PyPI installation).
 
 
+-----------------------------------------
+Configuring setup() using setup.cfg files
+-----------------------------------------
+
+``Setuptools`` allows using configuration files (usually `setup.cfg`)
+to define package’s metadata and other options which are normally supplied
+to ``setup()`` function.
+
+This approach not only allows automation scenarios, but also reduces
+boilerplate code in some cases.
+
+.. note::
+    Implementation presents limited compatibility with distutils2-like
+    ``setup.cfg`` sections (used by ``pbr`` and ``d2to1`` packages).
+
+    Namely: only metadata related keys from ``metadata`` section are supported
+    (except for ``description-file``); keys from ``files``, ``entry_points``
+    and ``backwards_compat`` are not supported.
+
+
+.. code-block:: ini
+
+    [metadata]
+    name = my_package
+    version = attr: src.VERSION
+    description = My package description
+    long_description = file: README.rst
+    keywords = one, two
+    license = BSD 3-Clause License
+
+    [metadata.classifiers]
+    Framework :: Django
+    Programming Language :: Python :: 3.5
+
+    [options]
+    zip_safe = False
+    include_package_data = True
+    packages = find:
+    scripts =
+      bin/first.py
+      bin/second.py
+
+    [options.package_data]
+    * = *.txt, *.rst
+    hello = *.msg
+
+    [options.extras_require]
+    pdf = ReportLab>=1.2; RXP
+    rest = docutils>=0.3; pack ==1.1, ==1.3
+
+
+Metadata and options could be set in sections with the same names.
+
+* Keys are the same as keyword arguments one provides to ``setup()`` function.
+
+* Complex values could be placed comma-separated or one per line
+  in *dangling* sections. The following are the same:
+
+  .. code-block:: ini
+
+      [metadata]
+      keywords = one, two
+
+      [metadata]
+      keywords =
+        one
+        two
+
+* In some cases complex values could be provided in subsections for clarity.
+
+* Some keys allow ``file:``, ``attr:`` and ``find:`` directives to cover
+  common usecases.
+
+* Unknown keys are ignored.
+
+
+Specifying values
+=================
+
+Some values are treated as simple strings, some allow more logic.
+
+Type names used below:
+
+* ``str`` - simple string
+* ``list-comma`` - dangling list or comma-separated values string
+* ``list-semi`` - dangling list or semicolon-separated values string
+* ``bool`` -  ``True`` is 1, yes, true
+* ``dict`` - list-comma where keys from values are separated by =
+
+
+Special directives:
+
+* ``attr:`` - value could be read from module attribute
+* ``file:`` - value could be read from a file
+* ``section:`` - values could be read from a dedicated (sub)section
+
+
+.. note::
+    ``file:`` directive is sandboxed and won't reach anything outside
+    directory with ``setup.py``.
+
+
+Metadata
+--------
+
+.. note::
+    Aliases given below are supported for compatibility reasons,
+    but not advised.
+
+=================  =================  =====
+Key                Aliases            Accepted value type
+=================  =================  =====
+name                                  str
+version                               attr:, str
+url                home-page          str
+download_url       download-url       str
+author                                str
+author_email       author-email       str
+maintainer                            str
+maintainer_email   maintainer-email   str
+classifiers        classifier         file:, section, list-comma
+license                               file:, str
+description        summary            file:, str
+long_description   long-description   file:, str
+keywords                              list-comma
+platforms          platform           list-comma
+provides                              list-comma
+requires                              list-comma
+obsoletes                             list-comma
+=================  =================  =====
+
+**version** - ``attr:`` supports callables; supports iterables;
+unsupported types are casted using ``str()``.
+
+
+Options
+-------
+
+=======================  =====
+Key                      Accepted value type
+=======================  =====
+zip_safe                 bool
+setup_requires           list-semi
+install_requires         list-semi
+extras_require           section
+entry_points             file, section
+use_2to3                 bool
+use_2to3_fixers          list-comma
+use_2to3_exclude_fixers  list-comma
+convert_2to3_doctests    list-comma
+scripts                  list-comma
+eager_resources          list-comma
+dependency_links         list-comma
+tests_require            list-semi
+include_package_data     bool
+packages                 find:, list-comma
+package_dir              dict
+package_data             section
+exclude_package_data     section
+namespace_packages       list-comma
+=======================  =====
+
+
+Configuration API
+=================
+
+Some automation tools may wish to access data from a configuration file.
+
+``Setuptools`` exposes ``read_configuration()`` function allowing
+parsing ``metadata`` and ``options`` sections into a dictionary.
+
+
+.. code-block:: python
+
+    from setuptools.config import read_configuration
+
+    conf_dict = read_configuration('/home/user/dev/package/setup.cfg')
+
+
+By default ``read_configuration()`` will read only file provided
+in the first argument. To include values from other configuration files
+which could be in various places set `find_others` function argument
+to ``True``.
+
+
 --------------------------------
 Extending and Reusing Setuptools
 --------------------------------