Commit Graph

29 Commits

Author SHA1 Message Date
James E. Blair f51dd26d25 Update autojob to handle branch regexes
Now that a job branch list can be a list of dictionaries, the autojob
directive can hit this error:

    variant = ', '.join(branches)
  TypeError: sequence item 0: expected str instance, dict found

Handle this by serializing the dictionaries with (str) so that we get
something printable.  It's not going to be pretty, but the old regexes
weren't either.

Change-Id: I9c0b242a8993760a7b7b27bbf231550c03cde183
2023-09-05 11:08:53 -07:00
Dr. Jens Harbott 2272117b40 Avoid infinite loop in find_zuul_yaml()
Currently there will be an infinite loop when no zuul config can be
found. Terminate the loop when we reach the filesystem root.

Signed-off-by: Dr. Jens Harbott <harbott@osism.tech>
Change-Id: I074f23eeac82531024cd1af0eeb7c502555eacd7
2022-05-03 20:54:25 +02:00
James E. Blair 202ca394fb Switch docs theme to versioned RTD
To match change I2870450ffd02f55509fcc1297d050b09deafbfb9 in Zuul.

Change-Id: Ic23dcbc743ca1c79bcead8eebd2899c00e0750c6
2021-12-16 11:23:09 -08:00
James E. Blair a8465c7cc1 Add :zuul:path support
This is to support documenting zookeeper paths in the Zuul developer
docs.

Change-Id: Id29eee89b38b34a3dac09750d6cabb442551e211
2021-11-11 15:06:53 -08:00
Zuul ca54cdca93 Merge "Ignore __pycache__ directory when looking at roles" 2020-11-10 23:01:41 +00:00
Clark Boylan 264a9fca1c Sort dirs and filenames when os.walk()ing
Zuul processes config files in zuul.d dirs in a sorted fashion. Emulate
this here so that the docs we produce are in line with the configs zuul
produces.

Change-Id: I83902efbb1161a0def436121aea2597a89044144
2020-04-29 09:13:28 -07:00
Clark Boylan 38bf2470b8 Handle directories in zuul.d/ configs
Prior to this change zuul-sphinx would error if there were directories
in zuul.d that needed to be processed recursively. This is because it
would try to open the directory as a normal file. Fix this by using
os.walk instead of os.listdir to iterate through the contents of the
zuul.d directory.

Additionally filter for .yaml files only as Zuul does this as well.

Change-Id: Id2d828d7842a86b7f89a2ce28a084e70f91d3f55
2020-04-29 09:13:27 -07:00
Ian Wienand e32f4e11f0 Ignore __pycache__ directory when looking at roles
For some reason, locally "tox -e docs" on zuul-jobs creates a
roles/__pycache__ directory; I think because it has a __init__.py
because we need that to correctly find unit-tests
(I9a653666e8a083fb7f3fbb92589fe0467a41e6e6).  I can not seem to
convince it to not write this directory.

Ignore __pycache__ directories when matching.

Change-Id: If7e70456a31554317c419fcb2ad3aad1ad19c6bf
2020-03-30 15:10:03 +11:00
Zuul 3cae816ab4 Merge "Raise an error if a file in zuul.d is empty" 2019-04-02 14:50:14 +00:00
Ian Wienand 6a0034ebca Add type to role variables
This brings this documentation into line with other values like attr
where you can specify the type of the variable.

The type output is added to each entry where appropriate, one minor
change is that we need to be less strict on the type lookup for
the hint suffix on sub-entries for types like "bool"

The documentation/test-case is updated.

Change-Id: Icc01ec6f04af97beeb085f6dbcf37b0d9dbed1fd
2019-03-11 16:53:37 +11:00
Gabriele Cerami 5f582c6eb3 Raise an error if a file in zuul.d is empty
Currently if a file in zuul.d is empty loading it returns None and the
command returns with a generic TypeError since data cannot be iterated.
This change adds a more explicit error.

Change-Id: I4928aac2488a92aed57018a3aa4d9f6f7650d38b
2018-09-28 13:58:23 +01:00
Ian Wienand 5bc7086580 Add attr-overview directive
This directive creates a bullet-point list of all the attributes
defined within a file.  The idea is to give a quick overview reference
for config file options.

There are two options to start with -- maxdepth is similar to the TOC
option and only shows certain levels of options; prefix allows to
filter down to a smaller set of options if required.

I've reworked the documentation examples as part of testing this.  The
various components are moved into separate files.  On the main page,
moved the config options into the main documentation (and use the zuul
attributes :) and pointed out that you can view the source of each
sample page to see how to generate what you see.

Change-Id: I6b0f414f50428c6e04b3aeb2a2c1f9196de80ce6
2018-09-28 20:18:28 +10:00
Ian Wienand 0210c9df03 Add example and type options to attributes
As described; this is used in the nodepool configuration
documentation.

Change-Id: Iad188fd69818762cc9bad927beaff55749e0385c
2018-09-26 07:34:17 +10:00
Ian Wienand 0165692e62 Use OrderedDict for object tracking
This makes iterating over the dict consistent on all python versions,
which is important if we're extracting them for a contents list or
similar.

Change-Id: I1a23bfc8fd032dd545cc48302ef469006b1f7a1e
2018-09-26 07:34:17 +10:00
James E. Blair 8f1cecfd74 Ignore non-directory entries in roles/
The check for whether a README.rst exists would naively look for
files like __init__.py/README.rst if there were files in the roles/
directory.  Only look for role directories instead.

Change-Id: I80268047a08b1294ccef841cd59894ec7133d16d
2018-09-05 10:18:18 -07:00
Zuul 6106a9051f Merge "Improve warning details" 2018-09-04 22:46:56 +00:00
Ian Wienand 6b9fa90602 Improve warning details
Currently, if you make a warning mistake in your inline YAML you get
warning output like:

 Warning, treated as error:
 /home/.../zuul.d:728:Unexpected indentation.

This doesn't give you any clue as to what was actually wrong.

Rework adding the content so that we add the job/template name as the
source.  You'll now get something like:

 Warning, treated as error:
 Job "failing-job" included in /home/.../doc/source/jobs.rst:6:Unexpected indentation.

which lets you know the job/template that is causing the error, and
where the auto include was sourced from.

Change-Id: I3144cb9bf689724d113c9b4b126f975f34f565c3
2018-09-04 11:04:10 +10:00
Ian Wienand a5136b73ad Warn when autoroles doesn't find a README.rst
This modifies autoroles to raise a warning when it finds a role
without a README.rst file.  This can be disabled with a config option
if you wish to build with warning-as-error but don't wish to document
roles.

Fix a typo in the readme for the zuul_role_paths

Add a test for the autoroles path detection by including a roles
directory under a subdir.  Manually removing the README.rst file has
validated that the warning is triggered.

Change-Id: Ia64298e6e910d21eb6f3830dd8b42e40e3444fa8
2018-08-24 14:09:22 +10:00
Ian Wienand 06eadf8e73 Add config option to find other roles
Add a new option to provide an additional list of directories to look
for roles to document.

Additionally, allow the 'roles/' top-level directory to not exist.

Needed-By: https://review.openstack.org/593478
Change-Id: I997c8bbece4917fe041aa9fd3dde13ee532fa2a6
2018-08-20 14:42:17 +10:00
Ian Wienand 44012c032b Open role readme files in utf-8 mode
I managed to get some hidden utf-8 characters into a zuul role
README.rst file which broke building in the gate on python 2.7 in a
rather mysterious way, deep inside the rst parser.

Make sure we open the README.rst files in unicode mode; this way the
lines are passed into the rst core as unicode and things go as
planned.

Change-Id: Id27062989c0527de545b18471eec29926955a4e4
2018-08-20 14:33:12 +10:00
Felix Schmidt 3ef1afe17e
Make the yaml parser aware of '!encrypted/' tags
Currently, the documentation generation for zuul jobs fails whenever a
secret is included in any of the yaml files that are parsed by the
zuul-sphinx extension.

This is because the yaml parser is not aware of the custom tag
'!encrypted/pkcs1-oaep' and therefore fails to initialize
an appropriate python object due to a missing constructor.

This results in the following error message:
"yaml.constructor.ConstructorError: could not determine a constructor
for the tag '!encrypted/pkcs1-oaep'"

Change-Id: Id011487615a3392affd627bbdcbdbe18e58206c5
2018-04-10 14:47:40 +02:00
James E. Blair aa62ecad86 Fix error in job parser
Change-Id: Id806d3648ad7464a2e6d1ae1235061f48014a49a
2017-10-18 15:56:21 -07:00
James E. Blair 4122b0b8f0 Add support for project-templates
Change-Id: I0f86acd7fb5e049e5368249de52f9d81a99936d8
2017-10-16 16:45:54 -07:00
Monty Taylor 15afdbadc8
Update exception message to include directories
Change-Id: Ifa0f907973b24422acd28e7a84a31919cff5acee
2017-09-19 15:58:41 -05:00
Monty Taylor 645c3d684d
Support zuul.d directories
Change-Id: I3a0cba537043ffbc554f1bb1cfe951d86587b014
2017-09-17 12:43:49 -05:00
James E. Blair ad1188ba7f Add jobvar and rolevar directives
Jobs and Roles frequently have the same variable names, so use
create unique directives and roles for each so that they are
easy to disambiguate.

This lets us say :jobvar:`tox.environment` rather than
:var:`job-tox.environment` which seems a bit arbitrary.

Change-Id: I9d72d11bfdb700037a6a08f92a2dbfa95ee519ad
2017-08-11 15:04:23 -07:00
James E. Blair 27322342f2 Import directives/roles from zuul
This imports the current directives from Zuul itself, and adds
an example doc page that exercises them all so this repo is more
self-testing.

Also, use python3 by default to ensure we remain py3 compat.

Change-Id: Ie5b3cedd5e8dfaf0763d09a901fc9ba0e5b63683
2017-08-07 16:45:27 -07:00
James E. Blair 9982e64ad5 Add setup to module import
This allows us to configure the extension as 'zuul_sphinx' rather
than 'zuul_sphinx.zuul'.

Change-Id: I8a1534f7c2614ee11411cf228de38931257fc970
2017-08-04 16:02:27 -07:00
James E. Blair 7342ef9e80 Initial commit
Copied from openstack-infra/zuul-jobs repo.

Change-Id: If76b2313dc54557d6271dbaba8d8bb555ed5eae8
2017-06-16 10:38:17 -07:00