Add mentions to the docs about the need for the C extension

4 files changed, 26 insertions, 9 deletions

diff --git a/CHANGES.rst b/CHANGES.rst
index 2167a534..222a63ee 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -31,7 +31,8 @@ Unreleased
   try to make the clickable detail pages more apparent.
 
 - ``coverage --help`` and ``coverage --version`` now mention which tracer is
-  installed, to help diagnose problems (`issue 479`_).
+  installed, to help diagnose problems. The docs mention which features need
+  the C extension. (`issue 479`_)
 
 .. _issue 440: https://bitbucket.org/ned/coveragepy/issues/440/yielded-twisted-failure-marked-as-missed
 .. _issue 472: https://bitbucket.org/ned/coveragepy/issues/472/html-report-indents-incorrectly-for-one
diff --git a/doc/cmd.rst b/doc/cmd.rst
index 5f3cc539..f0896de8 100644
--- a/doc/cmd.rst
+++ b/doc/cmd.rst
@@ -104,7 +104,9 @@ Coverage.py can measure multi-threaded programs by default. If you are using
 more exotic concurrency, with the `multiprocessing`_, `greenlet`_, `eventlet`_,
 or `gevent`_ libraries, then coverage.py will get very confused.  Use the
 ``--concurrency`` switch to properly measure programs using these libraries.
-Give it a value of ``greenlet``, ``eventlet``, or ``gevent``.
+Give it a value of ``multiprocessing``, ``thread``, ``greenlet``, ``eventlet``,
+or ``gevent``.  Values other than ``thread`` require the :ref:`C extension
+<install_extension>`.
 
 .. _multiprocessing: https://docs.python.org/2/library/multiprocessing.html
 .. _greenlet: http://greenlet.readthedocs.org/en/latest/
diff --git a/doc/install.rst b/doc/install.rst
index 1ccbed87..d362d6e5 100644
--- a/doc/install.rst
+++ b/doc/install.rst
@@ -57,15 +57,20 @@ The alternate old-school technique is:
 .. __: coverage_pypi_
 
 
-Installing dependencies
------------------------
+.. _install_extension:
+
+C Extension
+-----------
 
 Coverage.py includes a C extension for speed. It is strongly recommended to use
 this extension: it is much faster, and is needed to support a number of
-coverage.py features.  You may need to install the python-dev and gcc support
-files before installing coverage via pip.  The exact commands depend on which
-package manager you use on your operating system, which Python version you are
-using, and the names of the packages for your distribution.  For example::
+coverage.py features.  Most of the time, the C extension will be installed
+without any special action on your part.
+
+If you are installing on Linux, you may need to install the python-dev and gcc
+support files before installing coverage via pip.  The exact commands depend on
+which package manager you use, which Python version you are using, and the
+names of the packages for your distribution.  For example::
 
     $ sudo apt-get install python-dev gcc
     $ sudo yum install python-devel gcc
@@ -82,6 +87,9 @@ You can determine if you are using the extension by looking at the output of
 
 The first line will either say "with C extension," or "without C extension."
 
+A few features of coverage.py aren't supported without the C extension, such
+as concurrency and plugins.
+
 
 Installing on Windows
 ---------------------
diff --git a/doc/plugins.rst b/doc/plugins.rst
index 6161f888..3e7cee09 100644
--- a/doc/plugins.rst
+++ b/doc/plugins.rst
@@ -15,6 +15,9 @@ Coverage.py's behavior can be extended with third-party plugins.  A plugin is a
 separately installed Python class that you register in your .coveragerc.
 Plugins can be used to implement coverage measurement for non-Python files.
 
+Plugins are only supported with the :ref:`C extension <install_extension>`,
+which must be installed for plugins to work.
+
 Information about using plugins is on this page.  To write a plugin, see
 :ref:`api_plugin`.
 
@@ -51,7 +54,10 @@ coverage.py plugin called ``something.plugin``.
    Check the documentation for the plugin to see if it takes any options, and
    what they are.
 
-#. Run your tests with coverage.py as you usually would.
+#. Run your tests with coverage.py as you usually would.  If you get a message
+   like "Plugin file tracers (something.plugin) aren't supported with
+   PyTracer," then you don't have the :ref:`C extension <install_extension>`
+   installed.
 
 
 Available plugins