This updates zuul-sphinx to retrieve version info from package metadata
using importlib.metadata instead of the now removed pkg_resources
library. This is necessary to run doc builds on top of python3.12 which
removed setuptools and pkg_resources by default.
An altnerative would be to explicitly require setuptools as a dependency
but stdlib importlib should be sufficient so we don't bother.
Change-Id: I5d73e7cc728188e7978e30eb5eb53d73e74b9ce2
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
