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 e98ab6ea2b..9df6505817 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 @@ 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: diff --git a/doc/source/developer.rst b/doc/source/developer.rst new file mode 100644 index 0000000000..527ea6e43a --- /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 0000000000..65883812b5 --- /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 8c12138653..784fc4d96b 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -24,7 +24,7 @@ Contents: 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 0000000000..092754fe28 --- /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 aee896112b..36e83bd876 100644 --- a/zuul/driver/__init__.py +++ b/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 diff --git a/zuul/scheduler.py b/zuul/scheduler.py index 35ece79bbb..38187cf765 100644 --- a/zuul/scheduler.py +++ b/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):