Split the api docs into separate pages.

The :meth: references are annoying, and some aren't right yet. :(

6 files changed, 77 insertions, 60 deletions

diff --git a/coverage/control.py b/coverage/control.py
index 4837356d..ad3c1bdf 100644
--- a/coverage/control.py
+++ b/coverage/control.py
@@ -191,8 +191,8 @@ class Coverage(object):
         """Set all the initial state.
 
         This is called by the public methods to initialize state. This lets us
-        construct a Coverage object, then tweak its state before this function
-        is called.
+        construct a :class:`Coverage` object, then tweak its state before this
+        function is called.
 
         """
         if self._inited:
@@ -611,11 +611,12 @@ class Coverage(object):
     def start(self):
         """Start measuring code coverage.
 
-        Coverage measurement actually occurs in functions called after `start`
-        is invoked.  Statements in the same scope as `start` won't be measured.
+        Coverage measurement actually occurs in functions called after
+        :meth:`.start` is invoked.  Statements in the same scope as
+        :meth:`.start` won't be measured.
 
-        Once you invoke `start`, you must also call `stop` eventually, or your
-        process might not shut down cleanly.
+        Once you invoke :meth:`.start`, you must also call :meth:`.stop`
+        eventually, or your process might not shut down cleanly.
 
         """
         self._init()
@@ -695,8 +696,8 @@ class Coverage(object):
     def get_exclude_list(self, which='exclude'):
         """Return a list of excluded regex patterns.
 
-        `which` indicates which list is desired.  See `exclude` for the lists
-        that are available, and their meaning.
+        `which` indicates which list is desired.  See :meth:`.exclude` for the
+        lists that are available, and their meaning.
 
         """
         self._init()
@@ -739,7 +740,7 @@ class Coverage(object):
 
         Also warn about various problems collecting data.
 
-        Returns a :class:`CoverageData`, the collected coverage data.
+        Returns a :class:`coverage.CoverageData`, the collected coverage data.
 
         """
         self._init()
@@ -927,7 +928,7 @@ class Coverage(object):
         marker to indicate the coverage of the line.  Covered lines have ">",
         excluded lines have "-", and missing lines have "!".
 
-        See `coverage.report()` for other arguments.
+        See :meth:`.report` for other arguments.
 
         """
         self.get_data()
@@ -951,7 +952,7 @@ class Coverage(object):
         `title` is a text string (not HTML) to use as the title of the HTML
         report.
 
-        See `coverage.report()` for other arguments.
+        See :meth:`.report` for other arguments.
 
         Returns a float, the total percentage covered.
 
@@ -975,7 +976,7 @@ class Coverage(object):
         Each module in `morfs` is included in the report.  `outfile` is the
         path to write the file to, "-" will write to stdout.
 
-        See `coverage.report()` for other arguments.
+        See :meth:`.report` for other arguments.
 
         Returns a float, the total percentage covered.
 
diff --git a/coverage/data.py b/coverage/data.py
index 0fa2c878..56233e5e 100644
--- a/coverage/data.py
+++ b/coverage/data.py
@@ -22,13 +22,15 @@ class CoverageData(object):
 
     This class is the public supported API to the data coverage.py collects
     during program execution.  It includes information about what code was
+    executed. It does not include information from the analysis phase, to
+    determine what lines could have been executed, or what lines were not
     executed.
 
     .. note::
 
         The file format is not documented or guaranteed.  It will change in
-        the future, in possibly complicated ways.  Use this API to avoid
-        disruption.
+        the future, in possibly complicated ways.  Do not read coverage.py
+        data files directly.  Use this API to avoid disruption.
 
     There are a number of kinds of data that can be collected:
 
@@ -46,32 +48,33 @@ class CoverageData(object):
       written during "coverage run", and then accumulated during "coverage
       combine".
 
-    To read a coverage.py data file, use :meth:`read_file`, or :meth:`read` if
-    you have an already-opened file.  You can then access the line, arc, or
-    file tracer data with :meth:`lines`, :meth:`arcs`, or :meth:`file_tracer`.
-    Run information is available with :meth:`run_infos`.
+    To read a coverage.py data file, use :meth:`.read_file`, or :meth:`.read`
+    if you have an already-opened file.  You can then access the line, arc, or
+    file tracer data with :meth:`.lines`, :meth:`.arcs`, or
+    :meth:`.file_tracer`.  Run information is available with
+    :meth:`.run_infos`.
 
-    The :meth:`has_arcs` method indicates whether arc data is available.  You
-    can get a list of the files in the data with :meth:`measured_files`.
-    A summary of the line data is available from :meth:`line_counts`.  As with
+    The :meth:`.has_arcs` method indicates whether arc data is available.  You
+    can get a list of the files in the data with :meth:`.measured_files`.
+    A summary of the line data is available from :meth:`.line_counts`.  As with
     most Python containers, you can determine if there is any data at all by
     using this object as a boolean value.
 
 
     Most data files will be created by coverage.py itself, but you can use
-    methods here to create data files if you like.  The :meth:`set_lines`,
-    :meth:`set_arcs`, and :meth:`set_file_tracers` methods add data, in ways
-    that are convenient for coverage.py.  The :meth:`add_run_info` method adds
+    methods here to create data files if you like.  The :meth:`.set_lines`,
+    :meth:`.set_arcs`, and :meth:`.set_file_tracers` methods add data, in ways
+    that are convenient for coverage.py.  The :meth:`.add_run_info` method adds
     key-value pairs to the run information.
 
-    To add a file without any measured data, use :meth:`touch_file`.
+    To add a file without any measured data, use :meth:`.touch_file`.
 
-    You write to a named file with :meth:`write_file`, or to an already opened
-    file with :meth:`write`.
+    You write to a named file with :meth:`.write_file`, or to an already opened
+    file with :meth:`.write`.
 
-    You can clear the data in memory with :meth:`erase`.  Two data collections
-    can be combined by using :meth:`update` on one `CoverageData`, passing it
-    the other.
+    You can clear the data in memory with :meth:`.erase`.  Two data collections
+    can be combined by using :meth:`.update` on one :class:`CoverageData`,
+    passing it the other.
 
     """
 
diff --git a/doc/api.rst b/doc/api.rst
index 2904058b..1c20d3a4 100644
--- a/doc/api.rst
+++ b/doc/api.rst
@@ -15,10 +15,10 @@ Coverage.py API
 .. :history: 20140819T132600, change class name to Coverage
 
 
-The API to coverage.py is very simple, contained in a single module called
-`coverage`.  Most of the interface is in a single class, called
-`Coverage`.  Methods on the Coverage object correspond roughly to operations
-available in the command line interface. For example, a simple use would be::
+The API to coverage.py is very simple, contained in a module called `coverage`.
+Most of the interface is in the :class:`coverage.Coverage` class.  Methods on
+the Coverage object correspond roughly to operations available in the command
+line interface. For example, a simple use would be::
 
     import coverage
 
@@ -32,30 +32,11 @@ available in the command line interface. For example, a simple use would be::
 
     cov.html_report()
 
+The :class:`coverage.CoverageData` class provides access to coverage data
+stored in coverage.py data files.
 
-The Coverage class
-------------------
+.. toctree::
+    :maxdepth: 1
 
-.. module:: coverage
-
-.. autoclass:: Coverage
-    :members:
-    :exclude-members: use_cache
-    :special-members: __init__
-
-
-The CoverageData class
-----------------------
-
-.. autoclass:: CoverageData
-    :members:
-    :special-members: __init__
-
-
-Starting coverage.py automatically
-----------------------------------
-
-This function is used to start coverage measurement automatically when Python
-starts.  See :ref:`subprocess` for details.
-
-.. autofunction:: process_startup
+    api_coverage
+    api_coveragedata
diff --git a/doc/api_coverage.rst b/doc/api_coverage.rst
new file mode 100644
index 00000000..69b64c3b
--- /dev/null
+++ b/doc/api_coverage.rst
@@ -0,0 +1,21 @@
+.. 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_coverage:
+
+The Coverage class
+------------------
+
+.. autoclass:: coverage.Coverage
+    :members:
+    :exclude-members: use_cache, sys_info
+    :special-members: __init__
+
+
+Starting coverage.py automatically
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This function is used to start coverage measurement automatically when Python
+starts.  See :ref:`subprocess` for details.
+
+.. autofunction:: coverage.process_startup
diff --git a/doc/api_coveragedata.rst b/doc/api_coveragedata.rst
new file mode 100644
index 00000000..dec505c1
--- /dev/null
+++ b/doc/api_coveragedata.rst
@@ -0,0 +1,11 @@
+.. 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_coveragedata:
+
+The CoverageData class
+----------------------
+
+.. autoclass:: coverage.CoverageData
+    :members:
+    :special-members: __init__
diff --git a/doc/conf.py b/doc/conf.py
index de90dd74..1be0c4d8 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -58,7 +58,7 @@ copyright = u'2009\N{EN DASH}2015, Ned Batchelder'
 # The short X.Y version.
 version = '4.0'
 # The full version, including alpha/beta/rc tags.
-release = '4.0a6'
+release = '4.0b1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.