Separate the plugin API docs from the 'using plugins' docs.

6 files changed, 52 insertions, 23 deletions

diff --git a/coverage/plugin.py b/coverage/plugin.py
index ac407047..2f28777a 100644
--- a/coverage/plugin.py
+++ b/coverage/plugin.py
@@ -82,7 +82,9 @@ class CoveragePlugin(object):
         """Get the :class:`FileReporter` class to use for a file.
 
         This will only be invoked if `filename` returns non-None from
-        :meth:`file_tracer`.  It's an error to return None.
+        :meth:`file_tracer`.  It's an error to return None from this method.
+
+        Returns a :class:`FileReporter` object to use to report on `filename`.
 
         """
         _needs_to_implement(self, "file_reporter")
@@ -106,6 +108,9 @@ class FileTracer(object):
     way you like.  A natural choice would be to pass the file name given to
     `file_tracer`.
 
+    `FileTracer` objects should only be created in the
+    :meth:`CoveragePlugin.file_tracer` method.
+
     See :ref:`howitworks` for details of the different coverage.py phases.
 
     """
@@ -181,6 +186,9 @@ class FileReporter(object):
 
     See :ref:`howitworks` for details of the different coverage.py phases.
 
+    `FileReporter` objects should only be created in the
+    :meth:`CoveragePlugin.file_reporter` method.
+
     There are many methods here, but only :meth:`lines` is required, to provide
     the set of executable lines in the file.
 
diff --git a/doc/api.rst b/doc/api.rst
index 1c20d3a4..26db06ef 100644
--- a/doc/api.rst
+++ b/doc/api.rst
@@ -40,3 +40,4 @@ stored in coverage.py data files.
 
     api_coverage
     api_coveragedata
+    api_plugin
diff --git a/doc/api_coverage.rst b/doc/api_coverage.rst
index ddbe9a9f..70a57eef 100644
--- a/doc/api_coverage.rst
+++ b/doc/api_coverage.rst
@@ -3,11 +3,11 @@
 
 .. _api_coverage:
 
-.. :history: 20150802T174800, new file for 4.0b1
-
 The Coverage class
 ------------------
 
+.. :history: 20150802T174800, new file for 4.0b1
+
 .. module:: coverage
 
 .. autoclass:: Coverage
diff --git a/doc/api_coveragedata.rst b/doc/api_coveragedata.rst
index bd33dd55..75215a3d 100644
--- a/doc/api_coveragedata.rst
+++ b/doc/api_coveragedata.rst
@@ -3,11 +3,11 @@
 
 .. _api_coveragedata:
 
-.. :history: 20150802T174800, new doc for 4.0b1
-
 The CoverageData class
 ----------------------
 
+.. :history: 20150802T174800, new doc for 4.0b1
+
 .. versionadded:: 4.0
 
 .. module:: coverage
diff --git a/doc/api_plugin.rst b/doc/api_plugin.rst
new file mode 100644
index 00000000..dbea58bf
--- /dev/null
+++ b/doc/api_plugin.rst
@@ -0,0 +1,35 @@
+.. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
+.. For details: https://bitbucket.org/ned/coveragepy/src/default/NOTICE.txt
+
+.. _api_plugin:
+
+==============
+The Plugin API
+==============
+
+.. :history: 20150815T132400, new doc for 4.0b2
+
+.. versionadded:: 4.0
+
+.. module:: coverage
+
+The CoveragePlugin class
+------------------------
+
+.. autoclass:: CoveragePlugin
+    :members:
+    :member-order: bysource
+
+The FileTracer class
+--------------------
+
+.. autoclass:: FileTracer
+    :members:
+    :member-order: bysource
+
+The FileReporter class
+----------------------
+
+.. autoclass:: FileReporter
+    :members:
+    :member-order: bysource
diff --git a/doc/plugins.rst b/doc/plugins.rst
index 027b0b8f..93e7359c 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.
 
+Information about using plugins is on this page.  To write a plugin, see
+:ref:`api_plugin`.
+
 .. versionadded:: 4.0
 
 
@@ -49,21 +52,3 @@ coverage.py plugin called ``something.plugin``.
    what they are.
 
 #. Run your tests with coverage.py as you usually would.
-
-
-Plugin API
-----------
-
-.. module:: coverage
-
-.. autoclass:: CoveragePlugin
-    :members:
-    :member-order: bysource
-
-.. autoclass:: FileTracer
-    :members:
-    :member-order: bysource
-
-.. autoclass:: FileReporter
-    :members:
-    :member-order: bysource