Document how to define extension modules in setup.cfg
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 @@
.. 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 @@
| | 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 b657d14..aa8216f 100644
--- a/Doc/packaging/setupcfg.rst
+++ b/Doc/packaging/setupcfg.rst
@@ -141,6 +141,9 @@
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.
@@ -736,6 +739,35 @@
{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
----------------