From 383239cafccabec6b03d1a46d69da4c2376e4445 Mon Sep 17 00:00:00 2001
From: Stephen Finucane <stephen@that.guru>
Date: Thu, 26 Oct 2017 17:14:29 +0100
Subject: [PATCH] doc: Include collector config in the skip doc

None of the decorators are sufficient to skip an entire file, for
example if the file contain invalid code for a given Python version.
Simply link to details about customizing the collector.

Signed-off-by: Stephen Finucane <stephen@that.guru>
---
 doc/en/example/pythoncollection.rst | 30 +++++++++++++++--------------
 doc/en/skipping.rst                 | 12 +++++++++++-
 2 files changed, 27 insertions(+), 15 deletions(-)

diff --git a/doc/en/example/pythoncollection.rst b/doc/en/example/pythoncollection.rst
index 8d36c2e37..5fb63035a 100644
--- a/doc/en/example/pythoncollection.rst
+++ b/doc/en/example/pythoncollection.rst
@@ -175,21 +175,23 @@ You can always peek at the collection tree without running tests like this::
     
     ======= no tests ran in 0.12 seconds ========
 
-customizing test collection to find all .py files
----------------------------------------------------------
+.. _customizing-test-collection:
+
+Customizing test collection
+---------------------------
 
 .. regendoc:wipe
 
-You can easily instruct ``pytest`` to discover tests from every python file::
-
+You can easily instruct ``pytest`` to discover tests from every Python file::
 
     # content of pytest.ini
     [pytest]
     python_files = *.py
 
-However, many projects will have a ``setup.py`` which they don't want to be imported. Moreover, there may files only importable by a specific python version.
-For such cases you can dynamically define files to be ignored by listing
-them in a ``conftest.py`` file::
+However, many projects will have a ``setup.py`` which they don't want to be
+imported. Moreover, there may files only importable by a specific python
+version. For such cases you can dynamically define files to be ignored by
+listing them in a ``conftest.py`` file::
 
     # content of conftest.py
     import sys
@@ -198,7 +200,7 @@ them in a ``conftest.py`` file::
     if sys.version_info[0] > 2:
         collect_ignore.append("pkg/module_py2.py")
 
-And then if you have a module file like this::
+and then if you have a module file like this::
 
     # content of pkg/module_py2.py
     def test_only_on_python2():
@@ -207,13 +209,13 @@ And then if you have a module file like this::
         except Exception, e:
             pass
 
-and a setup.py dummy file like this::
+and a ``setup.py`` dummy file like this::
 
     # content of setup.py
     0/0  # will raise exception if imported
 
-then a pytest run on Python2 will find the one test and will leave out the
-setup.py file::
+If you run with a Python 2 interpreter then you will find the one test and will
+leave out the ``setup.py`` file::
 
     #$ pytest --collect-only
     ====== test session starts ======
@@ -225,13 +227,13 @@ setup.py file::
 
     ====== no tests ran in 0.04 seconds ======
 
-If you run with a Python3 interpreter both the one test and the setup.py file
-will be left out::
+If you run with a Python 3 interpreter both the one test and the ``setup.py``
+file will be left out::
 
     $ pytest --collect-only
     ======= test session starts ========
     platform linux -- Python 3.x.y, pytest-3.x.y, py-1.x.y, pluggy-0.x.y
     rootdir: $REGENDOC_TMPDIR, inifile: pytest.ini
     collected 0 items
-    
+
     ======= no tests ran in 0.12 seconds ========
diff --git a/doc/en/skipping.rst b/doc/en/skipping.rst
index f8cfb73ca..d6d1e2414 100644
--- a/doc/en/skipping.rst
+++ b/doc/en/skipping.rst
@@ -3,7 +3,7 @@
 .. _skipping:
 
 Skip and xfail: dealing with tests that cannot succeed
-=====================================================================
+======================================================
 
 You can mark test functions that cannot be run on certain platforms
 or that you expect to fail so pytest can deal with them accordingly and
@@ -142,6 +142,16 @@ will be skipped if any of the skip conditions is true.
 .. _`whole class- or module level`: mark.html#scoped-marking
 
 
+Skipping files or directories
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes you may need to skip an entire file or directory, for example if the
+tests rely on Python version-specific features or contain code that you do not
+wish pytest to run. In this case, you must exclude the files and directories
+from collection. Refer to :ref:`customizing-test-collection` for more
+information.
+
+
 Skipping on a missing import dependency
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~