More docs about plugins.

1 files changed, 36 insertions, 2 deletions

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: