Support [tool:pytest] in setup.cfg files

Also deprecate [pytest] usage in setup.cfg files

Fix #567

doc/en/customize.rst

@@ -50,7 +50,7 @@ Here is the algorithm which finds the rootdir from ``args``:
 
 Note that an existing ``pytest.ini`` file will always be considered a match,
 whereas ``tox.ini`` and ``setup.cfg`` will only match if they contain a
-``[pytest]`` section. Options from multiple ini-files candidates are never
+``[pytest]`` or ``[tool:pytest]`` section, respectively. Options from multiple ini-files candidates are never
 merged - the first one wins (``pytest.ini`` always wins, even if it does not
 contain a ``[pytest]`` section).
 
@@ -73,7 +73,7 @@ check for ini-files as follows::
 
     # first look for pytest.ini files
     path/pytest.ini
-    path/setup.cfg  # must also contain [pytest] section to match
+    path/setup.cfg  # must also contain [tool:pytest] section to match
     path/tox.ini    # must also contain [pytest] section to match
     pytest.ini
     ... # all the way down to the root
@@ -154,7 +154,7 @@ Builtin configuration file options
 
    .. code-block:: ini
 
-        # content of setup.cfg
+        # content of pytest.ini
         [pytest]
         norecursedirs = .svn _build tmp*
 

doc/en/example/pythoncollection.rst

@@ -77,9 +77,9 @@ Example::
 Changing directory recursion
 -----------------------------------------------------
 
-You can set the :confval:`norecursedirs` option in an ini-file, for example your ``setup.cfg`` in the project root directory::
+You can set the :confval:`norecursedirs` option in an ini-file, for example your ``pytest.ini`` in the project root directory::
 
-    # content of setup.cfg
+    # content of pytest.ini
     [pytest]
     norecursedirs = .svn _build tmp*
 
@@ -94,8 +94,9 @@ You can configure different naming conventions by setting
 the :confval:`python_files`, :confval:`python_classes` and
 :confval:`python_functions` configuration options.  Example::
 
-    # content of setup.cfg
-    # can also be defined in in tox.ini or pytest.ini file
+    # content of pytest.ini
+    # can also be defined in in tox.ini or setup.cfg file, although the section
+    # name in setup.cfg files should be "tool:pytest"
     [pytest]
     python_files=check_*.py
     python_classes=Check

doc/en/goodpractices.rst

@@ -196,6 +196,24 @@ required for calling the test command. You can also pass additional
 arguments to pytest such as your test directory or other
 options using ``--addopts``.
 
+You can also specify other pytest-ini options in your ``setup.cfg`` file
+by putting them into a ``[tool:pytest]`` section:
+
+.. code-block:: ini
+
+    [tool:pytest]
+    addopts = --verbose
+    python_files = testing/*/*.py
+
+
+.. note::
+    Prior to 3.0, the supported section name was ``[pytest]``. Due to how
+    this may collide with some distutils commands, the recommended
+    section name for ``setup.cfg`` files is now ``[tool:pytest]``.
+
+    Note that for ``pytest.ini`` and ``tox.ini`` files the section
+    name is ``[pytest]``.
+
 
 Manual Integration
 ^^^^^^^^^^^^^^^^^^

doc/en/xdist.rst

@@ -90,7 +90,7 @@ and ``pytest`` will run your tests. Assuming you have failures it will then
 wait for file changes and re-run the failing test set.  File changes are detected by looking at ``looponfailingroots`` root directories and all of their contents (recursively).  If the default for this value does not work for you you
 can change it in your project by setting a configuration option::
 
-    # content of a pytest.ini, setup.cfg or tox.ini file
+    # content of a pytest.ini or tox.ini file
     [pytest]
     looponfailroots = mypkg testdir
 
@@ -181,7 +181,7 @@ to run tests in each of the environments.
 Specifying "rsync" dirs in an ini-file
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-In a ``tox.ini`` or ``setup.cfg`` file in your root project directory
+In a ``pytest.ini`` or ``tox.ini`` file in your root project directory
 you may specify directories to include or to exclude in synchronisation::
 
     [pytest]