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
diff --git a/doc/source/internals.rst b/doc/source/datamodel.rst
similarity index 65%
rename from doc/source/internals.rst
rename to doc/source/datamodel.rst
index e98ab6e..9df6505 100644
--- a/doc/source/internals.rst
+++ b/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 @@
An abide is a collection of tenants.
+.. autoclass:: zuul.model.Tenant
.. autoclass:: zuul.model.UnparsedAbideConfig
.. autoclass:: zuul.model.UnparsedTenantConfig
@@ -85,34 +76,3 @@
.. 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:
diff --git a/doc/source/developer.rst b/doc/source/developer.rst
new file mode 100644
index 0000000..527ea6e
--- /dev/null
+++ b/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
diff --git a/doc/source/drivers.rst b/doc/source/drivers.rst
new file mode 100644
index 0000000..6588381
--- /dev/null
+++ b/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:
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 8c12138..784fc4d 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -24,7 +24,7 @@
launchers
statsd
client
- internals
+ developer
Indices and tables
==================
diff --git a/doc/source/testing.rst b/doc/source/testing.rst
new file mode 100644
index 0000000..092754f
--- /dev/null
+++ b/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:
diff --git a/zuul/driver/__init__.py b/zuul/driver/__init__.py
index aee8961..36e83bd 100644
--- a/zuul/driver/__init__.py
+++ b/zuul/driver/__init__.py
@@ -48,7 +48,8 @@
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 @@
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
diff --git a/zuul/scheduler.py b/zuul/scheduler.py
index 35ece79..38187cf 100644
--- a/zuul/scheduler.py
+++ b/zuul/scheduler.py
@@ -220,6 +220,26 @@
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):