Branch merge

2 files changed, 54 insertions, 20 deletions

diff --git a/Doc/library/packaging.compiler.rst b/Doc/library/packaging.compiler.rst
index dac6263..cf88685 100644
--- a/Doc/library/packaging.compiler.rst
+++ b/Doc/library/packaging.compiler.rst
@@ -569,10 +569,10 @@ extension modules.
 .. class:: Extension
 
    The Extension class describes a single C or C++ extension module.  It accepts
-   the following keyword arguments in its constructor
+   the following keyword arguments in its constructor:
 
    +------------------------+--------------------------------+---------------------------+
-   | argument name          | value                          | type                      |
+   | argument name          | value                          | type [#]_                 |
    +========================+================================+===========================+
    | *name*                 | the full name of the           | string                    |
    |                        | extension, including any       |                           |
@@ -670,3 +670,5 @@ extension modules.
    |                        | from the source extensions if  |                           |
    |                        | not provided.                  |                           |
    +------------------------+--------------------------------+---------------------------+
+
+.. [#] For values documented as lists, the given type is the type of each element.
diff --git a/Doc/packaging/setupcfg.rst b/Doc/packaging/setupcfg.rst
index d3fc07a9..aa8216f 100644
--- a/Doc/packaging/setupcfg.rst
+++ b/Doc/packaging/setupcfg.rst
@@ -141,13 +141,16 @@ files
    Modules, scripts, data, documentation and other files to include in the
    distribution.
 
+extension sections
+   Options used to build extension modules.
+
 command sections
    Options given for specific commands, identical to those that can be given
    on the command line.
 
 
 Global options
-==============
+--------------
 
 Contains global options for Packaging. This section is shared with Distutils.
 
@@ -185,7 +188,7 @@ setup_hook
 
 
 Metadata
-========
+--------
 
 The metadata section contains the metadata for the project as described in
 :PEP:`345`.  Field names are case-insensitive.
@@ -308,7 +311,7 @@ from the fields present in the file.
 
 
 Files
-=====
+-----
 
 This section describes the files included in the project.
 
@@ -352,7 +355,7 @@ Example::
 
 
 Resources
----------
+^^^^^^^^^
 
 This section describes the files used by the project which must not be installed
 in the same place that python modules or libraries, they are called
@@ -448,10 +451,10 @@ Where {datafir} category will be platform-dependent.
 
 
 More control on source part
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+"""""""""""""""""""""""""""
 
 Glob syntax
-"""""""""""
+'''''''''''
 
 When you declare source file, you can use a glob-like syntax to match multiples file, for example::
 
@@ -469,7 +472,7 @@ Glob tokens are:
 .. TODO Add examples
 
 Order of declaration
-""""""""""""""""""""
+''''''''''''''''''''
 
 The order of declaration is important if one file match multiple rules. The last
 rules matched by file is used, this is useful if you have this source tree::
@@ -492,7 +495,7 @@ one by one, you can declare them in this way::
        doc/README = {help}
 
 Exclude
-"""""""
+'''''''
 
 You can exclude some files of resources declaration by giving no destination, it
 can be useful if you have a non-resources file in the same directory of
@@ -513,12 +516,12 @@ Your **files** section will be::
        doc/RELEASES =
 
 More control on destination part
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+""""""""""""""""""""""""""""""""
 
 .. _setupcfg-resources-base-prefix:
 
 Defining a base prefix
-""""""""""""""""""""""
+''''''''''''''''''''''
 
 When you define your resources, you can have more control of how the final path
 is computed.
@@ -577,7 +580,7 @@ path will be::
 
 
 Overwriting paths for categories
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+""""""""""""""""""""""""""""""""
 
 This part is intended for system administrators or downstream OS packagers.
 
@@ -614,18 +617,18 @@ The platform-dependent categories are:
 
 
 Defining extra categories
-^^^^^^^^^^^^^^^^^^^^^^^^^
+"""""""""""""""""""""""""
 
 .. TODO
 
 
 Examples
-^^^^^^^^
+""""""""
 
 These examples are incremental but work unitarily.
 
 Resources in root dir
-"""""""""""""""""""""
+'''''''''''''''''''''
 
 Source tree::
 
@@ -647,7 +650,7 @@ So babar.sh and launch.sh will be placed in {scripts} directory.
 Now let's move all the scripts into a scripts directory.
 
 Resources in sub-directory
-""""""""""""""""""""""""""
+''''''''''''''''''''''''''
 
 Source tree::
 
@@ -673,7 +676,7 @@ scripts into {scripts} instead of {scripts}/scripts.
 Now let's add some docs.
 
 Resources in multiple sub-directories
-"""""""""""""""""""""""""""""""""""""
+'''''''''''''''''''''''''''''''''''''
 
 Source tree::
 
@@ -706,7 +709,7 @@ file is used.
 Now let's add some scripts for windows users.
 
 Complete example
-""""""""""""""""
+''''''''''''''''
 
 Source tree::
 
@@ -736,8 +739,37 @@ We use brace expansion syntax to place all the shell and batch scripts into
 {scripts} category.
 
 
+Extension sections
+------------------
+
+If a project includes extension modules written in C or C++, each one of them
+needs to have its options defined in a dedicated section.  Here's an example::
+
+   [files]
+   packages = coconut
+
+   [extension=_fastcoconut]
+   name = coconut._fastcoconut
+   language = cxx
+   sources = cxx_src/cononut_utils.cxx
+             cxx_src/python_module.cxx
+   include_dirs = /usr/include/gecode
+                  /usr/include/blitz
+   extra_compile_args =
+       -fPIC -O2
+       -DGECODE_VERSION=$(./gecode_version) -- sys.platform != 'win32'
+       /DGECODE_VERSION='win32' -- sys.platform == 'win32'
+
+The section name must start with ``extension=``; the righ-hand part is currently
+discarded.  Valid fields and their values are listed in the documentation of the
+:class:`packaging.compiler.extension.Extension` class; values documented as
+Python lists translate to multi-line values in the configuration file.  In
+addition, multi-line values accept environment markers on each line, after a
+``--``.
+
+
 Command sections
-================
+----------------
 
 To pass options to commands without having to type them on the command line
 for each invocation, you can write them in the :file:`setup.cfg` file, in a