More docs about plugins.

3 files changed, 70 insertions, 7 deletions

diff --git a/coverage/plugin.py b/coverage/plugin.py
index 32d654e4..e463e01d 100644
--- a/coverage/plugin.py
+++ b/coverage/plugin.py
@@ -6,8 +6,33 @@ from coverage.misc import _needs_to_implement
 
 
 class CoveragePlugin(object):
-    """Base class for coverage.py plugins."""
+    """Base class for coverage.py plugins.
+
+    To write a coverage.py plugin, create a subclass of `CoveragePlugin`.
+    You can override methods here to participate in various aspects of
+    coverage.py's processing.
+
+    Currently the only plugin type is a file tracer, for implementing
+    measurement support for non-Python files.  File tracer plugins implement
+    the :meth:`file_tracer` method to claim files and the :meth:`file_reporter`
+    method to report on those files.
+
+    Any plugin can optionally implement :meth:`sys_info` to provide debugging
+    information about their operation.
+
+    """
+
     def __init__(self, options):
+        """
+        When the plugin is constructed, it will be passed a dictionary of
+        plugin-specific options read from the .coveragerc configuration file.
+        The base class stores these on the `self.options` attribute.
+
+        Arguments:
+            options (dict): The plugin-specific options read from the
+                .coveragerc configuration file.
+
+        """
         self.options = options
 
     def file_tracer(self, filename):
@@ -38,7 +63,7 @@ class CoveragePlugin(object):
         """Return the FileReporter class to use for filename.
 
         This will only be invoked if `filename` returns non-None from
-        `file_tracer`.  It's an error to return None.
+        :meth:`file_tracer`.  It's an error to return None.
 
         """
         _needs_to_implement(self, "file_reporter")
@@ -46,8 +71,8 @@ class CoveragePlugin(object):
     def sys_info(self):
         """Return a list of information useful for debugging.
 
-        This method will be invoked for ``coverage run --debug=sys``.  Your
-        plugin can return any information to be displayed.
+        This method will be invoked for ``--debug=sys``.  Your
+        plugin can return any information it wants to be displayed.
 
         The return value is a list of pairs: (name, value).
 
@@ -208,7 +233,7 @@ class FileReporter(object):
         return False
 
     def flat_rootname(self):
-        """A base for a flat filename to correspond to this code unit.
+        """A base for a flat filename to correspond to this file.
 
         Useful for writing files about the code where you want all the files in
         the same directory, but need to differentiate same-named files from
diff --git a/doc/config.rst b/doc/config.rst
index f5bc06a1..df703ba9 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -11,6 +11,7 @@ Configuration files
 .. :history: 20110827T212700, updated for 3.5.1
 .. :history: 20130926T222300, updated for 3.6.1
 .. :history: 20140925T064700, updated for 4.0a1
+.. :history: 20150124T173400, updated for 4.0a4
 
 
 Coverage.py options can be specified in a configuration file.  This makes it
@@ -126,6 +127,9 @@ of measurement or reporting.  See :ref:`source` for details.
 id and random number to the data file name to simplify collecting data from
 many processes.  See :ref:`cmd_combining` for more information.
 
+``plugins`` (multi-string): a list of plugin package names. See :ref:`plugins`
+for more information.
+
 ``source`` (multi-string): a list of packages or directories, the source to
 measure during execution.  See :ref:`source` for details.
 
diff --git a/doc/plugin.rst b/doc/plugin.rst
index ba053242..d8f4ef56 100644
--- a/doc/plugin.rst
+++ b/doc/plugin.rst
@@ -1,4 +1,4 @@
-.. _plugin:
+.. _plugins:
 
 =======
 Plugins
@@ -6,8 +6,42 @@ Plugins
 
 .. :history: 20150124T143000, new page.
 
+Coverage.py's behavior can be extended by writing 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.
 
-.. automodule:: coverage.plugin
+Using plugins
+-------------
+
+To use a coverage.py plugin, you install it, and configure it.  For this
+example, let's say you want to use one called fred_plugin.
+
+#. Install the plugin as you would any other Python package::
+
+    pip install fred_plugin
+
+#. Configure coverage.py to use the plugin.  You do this by editing (or
+   creating) your .coveragerc file, as described in :ref:`config`.  The
+   ``plugins`` setting indicates your plugin::
+
+    [run]
+    plugins =
+        fred_plugin
+
+#. Run your tests as you usually would.  NOTE: You will see a warning when
+   coverage starts::
+
+    Coverage.py warning: Setting timid=True to support plugins.
+
+   This means that coverage will run slower than it usually would.  This
+   limitation is part of the initial alpha release, it will be gone in the
+   final version.
+
+
+Plugin API
+----------
+
+.. module:: coverage.plugin
 
 .. autoclass:: CoveragePlugin
     :members: