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: I19c575974bd57e27ae62f32271949de20dc67067
Since we're publishing to latest/ we should update the links to match.
Depends-On: https://review.opendev.org/825529
Change-Id: I16f920e8d99383bb2f87e155a1b7d6a65a385fcf
This adds a simplified version of the RTD version selector to doc
builds. It will list all tags at the time of the build, as well
as 'latest'.
Change-Id: I2870450ffd02f55509fcc1297d050b09deafbfb9
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
In I26be542a6d4f6266f7843ada5939172656b8b847 the documentation domain
was renamed to zuuldoc as a "temporary measure" :)
The zuul-sphinx project now has everything required for the Zuul
documentation, so we can switch the default domain to just "zuul" to
use it by default and remove the unsued "zuuldocs" domain provided by
zuul/sphinux/zuul.py.
This means you don't need to use :zuul:... to use things from
zuul-sphinx (this was rather confusing to debug, as we added :type:
support to :attr: some time ago in zuul-sphinx but it wasn't being
picked up, because it was using old internal versions).
Change-Id: I4f7a52a2d09671f042e2d6886e7916274f3ed931
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
Currently the title is showing up under the logo; the new version of
Sphinx/Alabaster apparently requires that we set the option this way.
Change-Id: Iea1a663f2efabf7e9430bb96256ea20b05f747ed
The website has added a badge people can use on their project pages. Add
some documentation about it.
Depends-On: https://review.openstack.org/568975
Change-Id: I97911f68d60f8be25f2eba66ccd8aeb9b1f34c49
The OpenStack Release team has created a great release notes management
tool that integrates with Sphinx. Start using it. For reference on how
to use it, see http://docs.openstack.org/developer/reno/
Add an initial release note with no contents so that the build flow and
docs integration can be verified. The note file can be removed later.
Change-Id: I254cd220fc8c0c06ee87f84f1fb5cbe3244f0fed
Since we have some python3 typehints in the code now, there is no need
to duplicate that information in sphinx docstrings.
sphinx-autodoc-typehints reads type annotations and updates :type:
information for :param: and :rtype: for :returns:. The results are the
same as if :param: had been given a type or a :type: directive, so this
is essentially just in service of using the same information for both
type hints/static analysis and for documentation.
There is a bug in the released version in that it does not consider
someone setting a default domain explicitly such as we do in zuul. A
pull request has been submitted that fixes the issue
Change-Id: I900a58eb6503cfee3cdff83e6cc376b5e2da3d44
Depends-On: https://github.com/agronholm/sphinx-autodoc-typehints/pull/19
This renames the internal sphinx domain from zuul to zuuldoc. This
is a temporary measure to avoid colliding with the domain defined
in zuul-sphinx (because of the initial data required, it's not
easy for us to simply add new directives/roles without at least
porting *some* of the framework into zuul-sphinx).
I expect to do that when this has stabilized.
Change-Id: I26be542a6d4f6266f7843ada5939172656b8b847
Depends-On: I8a1534f7c2614ee11411cf228de38931257fc970
The rtfd hook job just does an empty POST to a URI. There's no need to
allocate a node for that, we can just make REST calls from the executor.
Also, there is enough going on here that it needs to be documented. Add
a documentation section to the developer docs about what we're doing
with our ansible plugins. In support of that, add a simple sphinx domain
for ansible to allow us to easily link to upstream ansible documentation for
modules.
Change-Id: I9b0be1018388db7361aec10f30a70437de555615
We need to be able to link to configuration attributes, and they
should show up in the index. To that end, add some sphinx
directives to support config objects and attributes. These handle
nesting so that when we get deep into nested yaml (eg,
pipeline.trigger.gerrit.event) the full path will appear in the
header for the attribute. The ancestors will not be as prominent.
This ends up looking like the python class.FUNCTION() headers
in the stdlib docs.
The implementation is based on, and is compatible with, the nascent
zuul-sphinx module. Once that is published, we can either move
this code into that module, or depend on that module and add these
directives to the domain it creates.
The sphinx theme is changed to the current Sphinx default. That
is the theme "alabaster" (note, this is distinct from the theme
named "default", which is the old python2 style theme). Alabaster
has top-notch typography, and most importantly, it renders the
kinds of nested descriptors we're using very well.
Change-Id: I673b20849dd808e8fbff33fa1a7524227d1a6011
Sometimes having narrative text describing how objects hang together it
handy for knowing what to do.
Change-Id: Ib12af2d993740d82b4f43de74b11ecefd1cd363a
Adds programoutput sphinx extension as a test dependency so doc
builds can include the program help text.
Change-Id: Iec2f09f710162614cbb393a5628204ddebe2e29f
ASCII art is fun but not savvy for project managers and directors. This
patch slightly enhance the 'gating' documentation with colored diagrams.
This is made possible via http://blockdiag.com/ by Takeshi KOMIYA who
even took the time to write a sphinx extension. The version dependency
is at the very least 0.5.5, but might be higher :/
Change-Id: Ibe3c2674a5dff2114c40a84ffdec8a8886b1b21b
The intersphinx extensions let one reserve a link namespace and map it
to a remote URL, for example to refer to the Python documentation. A
drawback is that, from time to time, Sphinx will attempt to download an
object inventory from the remote, that is not convenient when running
sphinx in offline mode such as in a plane.
Change-Id: Idef8e88545715a3f1cb9ace002960a7ad3e37b69
Change-Id: I734f0f8237fb603ee41a39f06e63c007e79825a9
Reviewed-on: https://review.openstack.org/33350
Reviewed-by: James E. Blair <corvus@inaugust.com>
Reviewed-by: Doug Hellmann <doug.hellmann@dreamhost.com>
Approved: James E. Blair <corvus@inaugust.com>
Tested-by: Jenkins
On Debian, all binaries should have an associated manpage. While
building Zuul package we got the following lintian error:
W: zuul: binary-without-manpage usr/bin/zuul-server
This is easily fixed by making sphinx to name the man page zuul-server.
Change-Id: Ie9fa681654a8e7e8785c1dcfa5ec21ba27ae3049
Reviewed-on: https://review.openstack.org/29287
Reviewed-by: James E. Blair <corvus@inaugust.com>
Reviewed-by: Paul Belanger <paul.belanger@polybeacon.com>
Approved: Clark Boylan <clark.boylan@gmail.com>
Reviewed-by: Clark Boylan <clark.boylan@gmail.com>
Tested-by: Jenkins
When using sphinx-build to generate documentation, it would fail to
properly find our version information.
Change-Id: Iee14aa76b69ca9398688345cb2dcd0db9ecdaedc
Signed-off-by: Paul Belanger <paul.belanger@polybeacon.com>
Reviewed-on: https://review.openstack.org/25524
Reviewed-by: James E. Blair <corvus@inaugust.com>
Approved: Monty Taylor <mordred@inaugust.com>
Reviewed-by: Monty Taylor <mordred@inaugust.com>
Tested-by: Jenkins
The documentation files often have minor typo or badly formatted
commands which makes sphinx emits a warning. To make sure we always
catch them via the Jenkins build, this patch makes sphinx to convert
warning to errors thus aborting the build, simply add to pass the -W
option to sphinx-build.
This patch also fix some warnings:
* There is no source/_static dir so disable html_static_path
* In launchers.rst, File reference name should be before the title
Test plan:
$ make clean; make html
rm -rf build/*
sphinx-build -b html -d build/doctrees -W source build/html
Making output directory...
Running Sphinx v1.1.3
loading pickled environment... not yet created
loading intersphinx inventory from
http://docs.python.org/2.7/objects.inv...
building [html]: targets for 5 source files that are out of date
updating environment: 5 added, 0 changed, 0 removed
reading sources... [100%] zuul
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] zuul
writing additional files... genindex search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded.
Build finished. The HTML pages are in build/html.
$
Change-Id: Id907cc2c9aeccd077593b2fa1b78b220a159ed71
Reviewed-on: https://review.openstack.org/16316
Reviewed-by: Paul Belanger <paul.belanger@polybeacon.com>
Reviewed-by: Monty Taylor <mordred@inaugust.com>
Reviewed-by: Jeremy Stanley <fungi@yuggoth.org>
Reviewed-by: James E. Blair <corvus@inaugust.com>
Approved: Clark Boylan <clark.boylan@gmail.com>
Reviewed-by: Clark Boylan <clark.boylan@gmail.com>
Tested-by: Jenkins
After successfully adding openstack versioning to jenkins-job-builder
this add the same support for zuul.
Change-Id: Ia5baab2b0d9392c1b3c70bf890eaf7c6a2ea5c29
Signed-off-by: Paul Belanger <paul.belanger@polybeacon.com>
Reviewed-on: https://review.openstack.org/16219
Reviewed-by: James E. Blair <corvus@inaugust.com>
Approved: Monty Taylor <mordred@inaugust.com>
Reviewed-by: Monty Taylor <mordred@inaugust.com>
Tested-by: Jenkins
James E. Blair