Add Drivers to documentation

Re-organize the "internals" section into a "Developer's Guide" with
sub-pages and add the drivers documentation as one of them.

Change-Id: Ibdf0287a7a077dfeaac6c63d1c8beca8d5f3f4be

doc/source/datamodel.rst

@@ -1,15 +1,5 @@
-Zuul Internals
-==============
-
-While most people should not need to understand the details of Zuul's internal
-data model, understanding the data model is essential for people writing
-code for Zuul, and might be interesting to advanced users. The model is
-defined in `zuul/model.py`_.
-
-.. _zuul/model.py: http://git.openstack.org/cgit/openstack-infra/zuul/tree/zuul/model.py
-
 Data Model
-----------
+==========
 
 It all starts with the :py:class:`~zuul.model.Pipeline`. A Pipeline is the
 basic organizational structure that everything else hangs off.
@@ -74,6 +64,7 @@ Tenants
 
 An abide is a collection of tenants.
 
+.. autoclass:: zuul.model.Tenant
 .. autoclass:: zuul.model.UnparsedAbideConfig
 .. autoclass:: zuul.model.UnparsedTenantConfig
 
@@ -85,34 +76,3 @@ Other Global Objects
 .. autoclass:: zuul.model.RepoFiles
 .. autoclass:: zuul.model.Worker
 .. autoclass:: zuul.model.TriggerEvent
-
-
-Testing
--------
-
-Zuul provides an extensive framework for performing functional testing
-on the system from end-to-end with major external components replaced
-by fakes for ease of use and speed.
-
-Test classes that subclass :py:class:`~tests.base.ZuulTestCase` have
-access to a number of attributes useful for manipulating or inspecting
-the environment being simulated in the test:
-
-.. autoclass:: tests.base.ZuulTestCase
-   :members:
-
-.. autoclass:: tests.base.FakeGerritConnection
-   :members:
-   :inherited-members:
-
-.. autoclass:: tests.base.FakeGearmanServer
-   :members:
-
-.. autoclass:: tests.base.RecordingLaunchServer
-   :members:
-
-.. autoclass:: tests.base.FakeBuild
-   :members:
-
-.. autoclass:: tests.base.BuildHistory
-   :members:

doc/source/developer.rst

@@ -0,0 +1,15 @@
+Developer's Guide
+=================
+
+This section contains information for Developers who wish to work on
+Zuul itself.  This information is not necessary for the operation of
+Zuul, though advanced users may find it interesting.
+
+.. autoclass:: zuul.scheduler.Scheduler
+
+.. toctree::
+   :maxdepth: 1
+
+   datamodel
+   drivers
+   testing

doc/source/drivers.rst

@@ -0,0 +1,20 @@
+Drivers
+=======
+
+Zuul provides an API for extending its functionality to interact with
+other systems.
+
+.. autoclass:: zuul.driver.Driver
+   :members:
+
+.. autoclass:: zuul.driver.ConnectionInterface
+   :members:
+
+.. autoclass:: zuul.driver.SourceInterface
+   :members:
+
+.. autoclass:: zuul.driver.TriggerInterface
+   :members:
+
+.. autoclass:: zuul.driver.ReporterInterface
+   :members:

doc/source/index.rst

@@ -24,7 +24,7 @@ Contents:
    launchers
    statsd
    client
-   internals
+   developer
 
 Indices and tables
 ==================

doc/source/testing.rst

@@ -0,0 +1,29 @@
+Testing
+=======
+
+Zuul provides an extensive framework for performing functional testing
+on the system from end-to-end with major external components replaced
+by fakes for ease of use and speed.
+
+Test classes that subclass :py:class:`~tests.base.ZuulTestCase` have
+access to a number of attributes useful for manipulating or inspecting
+the environment being simulated in the test:
+
+.. autoclass:: tests.base.ZuulTestCase
+   :members:
+
+.. autoclass:: tests.base.FakeGerritConnection
+   :members:
+   :inherited-members:
+
+.. autoclass:: tests.base.FakeGearmanServer
+   :members:
+
+.. autoclass:: tests.base.RecordingLaunchServer
+   :members:
+
+.. autoclass:: tests.base.FakeBuild
+   :members:
+
+.. autoclass:: tests.base.BuildHistory
+   :members:

zuul/driver/__init__.py

@@ -48,7 +48,8 @@ class Driver(object):
         configuration) as an argument.  The driver may establish any
         global resources needed by the tenant at this point.
 
-        :arg Tenant tenant: The tenant which has been reconfigured.
+        :arg Tenant tenant: The :py:class:`zuul.model.Tenant` which has been
+            reconfigured.
 
         """
         pass
@@ -61,7 +62,8 @@ class Driver(object):
         This method is called once during initialization to allow the
         driver to store a handle to the running scheduler.
 
-        :arg Scheduler scheduler: The current running scheduler.
+        :arg Scheduler scheduler: The current running
+           :py:class:`zuul.scheduler.Scheduler`.
 
         """
         pass

zuul/scheduler.py

@@ -220,6 +220,26 @@ def toList(item):
 
 
 class Scheduler(threading.Thread):
+    """The engine of Zuul.
+
+    The Scheduler is reponsible for recieving events and dispatching
+    them to appropriate components (including pipeline managers,
+    mergers and launchers).
+
+    It runs a single threaded main loop which processes events
+    received one at a time and takes action as appropriate.  Other
+    parts of Zuul may run in their own thread, but synchronization is
+    performed within the scheduler to reduce or eliminate the need for
+    locking in most circumstances.
+
+    The main daemon will have one instance of the Scheduler class
+    running which will persist for the life of the process.  The
+    Scheduler instance is supplied to other Zuul components so that
+    they can submit events or otherwise communicate with other
+    components.
+
+    """
+
     log = logging.getLogger("zuul.Scheduler")
 
     def __init__(self, config, testonly=False):