Commit Graph

12 Commits

Author SHA1 Message Date
James E. Blair 1d3013e68f Avoid sphinx 7.2.5
There is a bug currently being investigated, and it breaks us:
https://github.com/sphinx-doc/sphinx/issues/11662

Change-Id: Ic51903a86ae5b5c75e65741b94ff0889aa6b72d0
2023-08-31 08:55:59 -07:00
James E. Blair 6e935f3ad7 Pin pillow for docs build
Pillow released 10.0.0 and sphinxcontrib-blockdiag is not compatible
with it.

Looking at the blockdiag repo, I fear we may need to find an alternative.

Change-Id: I8d4b5999619aa3be90000b5c23ad33f8706306eb
2023-07-06 10:38:10 -07:00
James E. Blair 40f53a8502 Require sphinx-rtd-theme >= 1.2.2
The sphinx-rtd-theme package is not yet compatible with sphinx 7.

The 1.2.2 version of the theme pins sphinx to <7 which does work and
allows us to have a transitive pin on sphinx that will be auto-removed
once sphinx-rtd-theme is updated to work with sphinx 7 and released.

Change-Id: Ib6771ebe5a30892ee16499f2434fe48e018e877c
2023-06-23 16:06:39 -07:00
Ian Wienand 2438e4692e doc: uncap sphinx
The issue referenced inline was fixed by [1] and is in
sphinx-contrib/httpdomain 1.8.0, so we can uncap Sphinx now.  This has
the nice side-effect of fixing another problem; Sphinx 4.1.0 doesn't
work with Python 3.10 [2] :)

[1] e3d99f530b
[2] https://github.com/sphinx-doc/sphinx/issues/9562

Change-Id: I910f237f6aff3c3a3f664d3dd8f16042b63857a5
2022-04-12 06:27:24 +00:00
Jeremy Stanley 77d191d4fb Increase our Sphinx minimum to 1.8
Since I11f165f59c099f3ab4a2fe4fcd0cb421cfd43285 has added
html_baseurl to our Sphinx config for RFC 5988 support, which is
only implemented in 1.8 and later, increase the minimum version we
declare as needed in the doc/requirements.txt file.

Change-Id: I264bb9e52fac31b093b3e8b343446a0ff3a02da4
2022-01-20 19:21:36 +00:00
James E. Blair bd07ddfabc Reorganize docs
This is an attempt to reorganize docs based on what we've learned so far:

* Audience is important -- help users find the job syntax reference without
  getting bogged down in how to run zookeeper.
* Having distinct tutorials, howtos, and reference documentation is helpful.
* Grouping by subject matter is important; users shouldn't have to open tabs
  with howto, reference, and tutorial to synthesize all the information on
  a subject.

This reorg reduces the use of explicit reference/howto/tutorial/discussion
divisions since in some cases they never got sufficiently fleshed out (eg,
user tutorials), and in others the information was spread too thinly across
them all (eg authentication).  However, those distinctions are still useful,
and the new organization reflects that somewhat.

I have made only some changes to content (generally in introductory sections
in order to make things make sense) and added a new "about Zuul" page.  We
should still go through the documentation and update it and tweak the organization
further.  This is mostly an attempt to get a new framework in place.

The theme is switched from alabaster to RTD.  That's because RTD has really
good support for a TOC tree in the side bar with expansion.  That makes a big
difference when trying to navigate large documentation like this.  The new
framework is intended to have very good left-hand navigation for users.

Change-Id: I5ef88536acf1a1e58a07827e06b07d06588ecaf1
2021-12-15 15:25:31 -08:00
James E. Blair 85dc6d6868 Pin mistune
This is a transitive dep of the openapi sphinx plugin, and it just
released a 2.0 which is incompatible with it; this causes docs builds
to fail.  Pin it until that is fixed.

Change-Id: Ic6a2a6520a6d4079f7d81e318316b46b68982cf3
2021-12-06 11:48:10 -08:00
Ian Wienand 60a8f2ad74 Pin sphinx < 4.1.0
This release appears to have broken the docs build.  Unfortunately it
looks like an issue in the sphinx-contrib/httpdomain project related
to [1] so will require some external releases to fix.

[1] https://github.com/sphinx-doc/sphinx/pull/9155

Change-Id: I1d3a2bf7c399e9e008f1739237fe5455edde57ba
2021-07-13 16:27:01 +10:00
Matthieu Huin c6f89dc270 tools: Deprecate encrypt_secret.py, document zuul-client encrypt
Now that zuul-client's encrypt subcommand covers the same
functionalities as encrypt_secret.py, add a deprecation
message when running the script. Document the zuul-client
encrypt command in the doc section about secrets.

Change-Id: Id5437ffbb688cb80b2744db3beeaa28c97080d90
Depends-On: https://review.opendev.org/765313
2020-12-09 11:30:59 +00:00
Tristan Cacqueray 85616c4c09 web: add OpenAPI documentation
This change adds a swagger description of the REST API. The description is
rendered in the sphinx user documentations and in the web interface.

Change-Id: I753524f40a09874dab5952f14ab17025525bbab9
2019-06-12 22:35:13 +02:00
Tobias Henkel cd9827e664
Manage ansible installations within zuul
As a first step towards supporting multiple ansible versions we need
tooling to manage ansible installations. This moves the installation
of ansible from the requirements.txt into zuul. This is called as a
setup hook to install the ansible versions into
<prefix>/lib/zuul/ansible. Further this tooling abstracts knowledge
that the executor must know in order to actually run the correct
version of ansible.

The actual usage of multiple ansible versions will be done in
follow-ups.

For better maintainability the ansible plugins live in
zuul/ansible/base where plugins can be kept in different versions if
necessary. For each supported ansible version there is a specific
folder that symlinks the according plugins.

Change-Id: I5ce1385245c76818777aa34230786a9dbaf723e5
Depends-On: https://review.openstack.org/623927
2019-03-15 09:09:16 +01:00
Andreas Jaeger cb9e1b4885 Use doc/requirements.txt
Create separate doc/requirements.txt file and use it, this shrinks
the list of requirements to install for a normal run.

Change-Id: I7c27f7f737657005ab6e370ae7e5dceb5a7073e7
2018-10-28 16:59:15 +01:00