54 Commits

Author SHA1 Message Date
Jeremy Stanley
4a4f162668 Switch logo color in docs pages to dark blue
The trademark for the logo, as filed, is specified as dark blue.
That logo needs to be displayed in a user guide or manual or
alongside a direct download of the software in order to demonstrate
continued use of the mark, and the foundation's trademark lawyers
have expressed concern that a white version is insufficient (but
they seem to be okay with the current background color as long as
the lines of the logo are colored similar to the version on file).

This is a copy of the equivalent change from the zuul repository.

Co-Authored-By: James E. Blair <jim@acmegating.com>
Depends-On: https://review.opendev.org/934443
Change-Id: I5bc28f0117e26e451f77fb0946ee1de44beb6852
2024-11-12 12:42:07 -08:00
Clark Boylan
f8b00a88f2 Replace pbr and pkg_resource version info with importlib.metadata
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
2024-11-12 12:42:07 -08:00
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
0.7.0
2023-09-05 11:08:53 -07:00
Clark Boylan
9f8accfdad Convert zuul-sphinx to nox
Zuul projects are moving from tox to nox due to incompatibilities in
tox v4. This updates zuul-sphinx to nox.

Change-Id: Iccd3c36620ae452c81e9c317a7b2d73fd2061ced
2022-12-29 11:09:09 -08: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
6acbcbb2f9 Correct tagged version docs build
A variable reassignment in conf.py caused errors when we try to build
release versions of docs.  Correct that by swapping the order of use
and assignment.

Change-Id: Ica90e9c0cc20aa590ad0177a0ceab72f4f4c6b5b
2022-03-21 10:28:29 -07: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
f58c596eae Set project vars to match Zuul
Since we use the zuul python release jobs, we should set these
variables to match.  They currently fail attempting to install
Node v6.

Change-Id: I92f54154675ea1844fa1dee3dfe3931b7e80f785
2021-11-23 10:08:02 -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
0.6.0
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
Zuul
ee017c1872 Merge "Switch to zuul-release-python" 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
0.5.0
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
Tristan Cacqueray
82799986a5 Switch to zuul-release-python
This change replaces opendev-release-python by zuul-release-python to enable
source tarball to be published to https://tarballs.opendev.org/zuul

Change-Id: Ic1955140edbbec4633d7dce8145a2f8db59a3189
2019-09-16 14:51:20 +00:00
OpenDev Sysadmins
6a29830441 OpenDev Migration Patch
This commit was bulk generated and pushed by the OpenDev sysadmins
as a part of the Git hosting and code review systems migration
detailed in these mailing list posts:

http://lists.openstack.org/pipermail/openstack-discuss/2019-March/003603.html
http://lists.openstack.org/pipermail/openstack-discuss/2019-April/004920.html

Attempts have been made to correct repository namespaces and
hostnames based on simple pattern matching, but it's possible some
were updated incorrectly or missed entirely. Please reach out to us
via the contact information listed at https://opendev.org/ with any
questions you may have.
2019-04-19 19:25:30 +00:00
James E. Blair
a1fdd21616 Run opendev-release-python on release
This is a python release job for the new tenant.

Change-Id: Idf64ce7fac50af47fd65bbc61164a7bc5b9c0e90
2019-04-02 14:53:52 -07:00
Zuul
3cae816ab4 Merge "Raise an error if a file in zuul.d is empty" 2019-04-02 14:50:14 +00:00
James E. Blair
690e5eee78 Publish docs on release
Change-Id: I8c1ce431f369bd5706360bda018d4ace6839b26a
Depends-On: https://review.openstack.org/648777
2019-03-29 13:56:47 -07:00
James E. Blair
e44c1ba815 Update to new docs jobs
These are zuul-tenant-specific and are built for the promote
pipeline.

Change-Id: I369a80d75dc70ed773c5c4174aa6004f6383831e
0.4.1
2019-03-29 08:58:45 -07: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
0.4.0
2019-03-11 16:53:37 +11:00
Zuul
1a2258eb5c Merge "Use tox-docs directly" 2018-10-29 12:25:29 +00: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
0.3.0
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
Andreas Jaeger
710b99539a Use tox-docs directly
Use tox-docs instead of build-tox-docs template that is defined in
openstack-zuul-jobs.

Change-Id: I7c7679277184f95f851c8db3208a8f43f03bc7c4
2018-09-13 09:24:14 +02: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
0.2.5
2018-09-05 10:18:18 -07:00
Zuul
6106a9051f Merge "Improve warning details" 0.2.4 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
Zuul
046c5e548c Merge "Update docs build job" 2018-08-22 11:32:04 +00:00
Andreas Jaeger
c352f5b1ad Update docs build job
Use tox -e docs for building with the new build-tox-docs template.
Update tox.ini to use sphinx-build directly.

Change-Id: Idd8110051a78f96ed28848ff9836ade3fa59329b
2018-08-21 21:08:23 +02: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
0.2.3
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
James E. Blair
fb48c1fe3d Stop publishing to docs.openstack.org
Change-Id: I115229c06b8372099125072be7b415a67fdea263
Depends-On: https://review.openstack.org/582322
2018-07-12 11:12:28 -07:00
James E. Blair
064feaa430 Add logo to docs
Change-Id: Id99b12f30c39eeaabf4696555c92ee4fae3a2f82
2018-05-04 14:52:18 -07:00
Zuul
2516aeff56 Merge "Make the yaml parser aware of '!encrypted/' tags" 0.2.2 2018-04-12 19:44:46 +00:00
James E. Blair
80cffd1987 Add build-sphinx check/gate jobs
I accidentally removed this in an earlier restructuring.

Change-Id: I913cd2e804985951b32ad442f5e9ab8488508e74
2018-04-10 10:20:16 -07: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
12b3f457bd Publish docs to zuul-ci.org
Also, move the publish-to-infra job into this repo for consistency.

Change-Id: I05275f167cfa114df9e437cf8730fe7ab8d6192b
2018-03-22 16:11:10 -07:00
James E. Blair
aa62ecad86 Fix error in job parser
Change-Id: Id806d3648ad7464a2e6d1ae1235061f48014a49a
0.2.1
2017-10-18 15:56:21 -07:00
James E. Blair
4122b0b8f0 Add support for project-templates
Change-Id: I0f86acd7fb5e049e5368249de52f9d81a99936d8
0.2.0
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
0.1.6
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
0.1.5
2017-08-11 15:04:23 -07:00
Monty Taylor
1cb9f8fa02
Mark zuul-sphinx as supporting python3
We test it and use it in python3, so go ahead and mark that in
setup.cfg. Also, update the homepage to the zuul-sphinx docs.

Change-Id: I27be701e0c74af88a8bbe317b3f753ed57892a5d
0.1.4
2017-08-09 11:57:03 -05: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
553fdce0cf Change usage from zuul_sphinx.zuul to zuul_sphinx
Change-Id: I6ca81675981a653cbf403b4870550d5b9b46a793
0.1.3
2017-08-04 16:22:26 -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