Rename plugin.rst to plugins.rst

1 files changed, 53 insertions, 0 deletions

diff --git a/doc/plugins.rst b/doc/plugins.rst
new file mode 100644
index 0000000..d8f4ef5
--- /dev/null
+++ b/doc/plugins.rst
@@ -0,0 +1,53 @@
+.. _plugins:
+
+=======
+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.
+
+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:
+
+.. autoclass:: FileTracer
+    :members:
+
+.. autoclass:: FileReporter
+    :members: