930dd24dd2
Sphinx was pinned to >1.5.0 <=1.7.0 4 years ago. It is now on v4.4.0,
and we're seeing an incompatibility with the latest version of jinja2.
Along with updating the Sphinx version, this also includes fixes for
several warnings generated in the latest version:
* Outdated docs due to the removal of the "parser" param from
Base.get_xml
* Class lookup issues
* External links for which we have extlinks defined
* Deprated PyModulelevel is replaced by PyFunction
* sphinx.ext.autodoc.Documenter.get_doc signature changed
Signed-off-by: Eric Ball <eball@linuxfoundation.org>
Change-Id: Iba65fb724f098f3e4a0b20f2a183cb2ea3c450ea
2.9 KiB
Extending
Jenkins Job Builder is quite modular. It is easy to add new attributes to existing components, a new module to support a Jenkins plugin, or include locally defined methods to deal with an idiosyncratic build system.
The Builder
The Builder class manages Jenkins jobs. It's responsible
for creating/deleting/updating jobs and can be called from your
application. You can pass it a filename or an open file-like object that
represents your YAML configuration. See the
jenkins_jobs/builder.py file for more details.
XML Processing
Most of the work of building XML from the YAML configuration file is
handled by individual functions that implement a single characteristic.
For example, see the jenkins_jobs/modules/builders.py file
for the Python module that implements the standard Jenkins builders. The
shell function at the top of the file implements the
standard Execute a shell build step. All
of the YAML to XML functions in Jenkins Job Builder have the same
signature:
:arg class:xml.etree.ElementTree xml_parent: this attribute's parent XML element :arg dict data: the YAML data structure for this attribute and below
The function is expected to examine the YAML data structure and create new XML nodes and attach them to the xml_parent element. This general pattern is applied throughout the included modules.
Modules
Nearly all of Jenkins Job Builder is implemented in modules. The main program has no concept of builders, publishers, properties, or any other aspects of job definition. Each of those building blocks is defined in a module, and due to the use of setuptools entry points, most modules are easily extensible with new components.
To add a new module, define a class that inherits from :pyjenkins_jobs.modules.base.Base, and add it to the
jenkins_jobs.modules entry point in your setup.py.
jenkins_jobs.modules.base.Base
Components
Most of the standard modules supply a number of components, and it's
easy to provide your own components for use by those modules. For
instance, the Builders module provides several builders, such as the
shell builder as well as the trigger_builds builder. If you wanted to add a
new builder, all you need to do is write a function that conforms to the
Component Interface <component_interface>, and
then add that function to the appropriate entry point (via a setup.py
file).
Module Registry
All modules and their associated components are registered in the module registry. It can be accessed either from modules via the registry field, or via the parser parameter of components.
jenkins_jobs.registry.ModuleRegistry