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
This commit is contained in:
James E. Blair 2017-01-19 10:35:24 -08:00
parent 2f001c05a1
commit e4de4f44dd
7 changed files with 91 additions and 45 deletions

View File

@ -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:

15
doc/source/developer.rst Normal file
View File

@ -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

20
doc/source/drivers.rst Normal file
View File

@ -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:

View File

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

29
doc/source/testing.rst Normal file
View File

@ -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:

View File

@ -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

View File

@ -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):