Hey everybody!
Following recent changes [0] in the PTI [1][2] we're rolling out some
changes to the build-openstack-releasenotes and
build-openstack-sphinx-docs jobs. If you see patches with the topic
'updated-pti' - they are in service of this.
The most important thing to be aware of is that we'll no longer be using
tox for either of them. There are a few reasons for that - the one
that's most important to me is that it allows us to use the exact same
docs and releasenotes build jobs for python, go, javascript or any other
language without needing to add python build tooling to non-python
repos. We'll also align more with how readthedocs does things in the
broader python ecosystem.
It's also worth reminding people that we've NEVER used 'tox -edocs' in
the gate for docs jobs - so anyone who has additional things in their
docs environment has not been having those things run. For folks running
doc8, we recommend adding those checks to your pep8 environment instead.
It's also worth noting that we're adding support for a
doc/requirements.txt file (location chosen for alignment readthedocs) to
express requirements needed for all docs (for both releasenotes and
docs). We'll start off falling back to test-requirements.txt ... but, we
recommend splitting doc related requirements into doc/requirements.txt -
since that will mean not needing to install Sphinx when doing tox unittests.
Specific info
=============
Releasenotes
------------
The patches for releasenotes have been approved and merged.
* We use -W for all releasenotes builds - this means warnings are always
errors for releasenotes. That shouldn't bother anyone, as most of the
releasenotes content is generated by reno anyway.
* We're temporarily installing the project to get version number. Doing
this will be removed as soon as the changes in
topic:releasenotes-version land. Note this only changes the version
number on the front page, not what is shown. topics:releasenotes-version
* Installs dependencies via bindep for doc environment.
* doc/requirements.txt is used for installation of python dependencies.
Things like whereto or openstackdocstheme should go there.
Documentation builds
--------------------
* We use -W only if setup.cfg sets it
* Installs dependencies via bindep for doc environment. Binary deps,
such as graphviz, should be listed in bindep and marked with a 'doc' tag.
* doc/requirements.txt is used for installation of python dependencies.
Things like whereto or openstackdocstheme should go there.
* tox_install.sh used to install project if it exists. Because of the
current situation with neutron and horizon plugins it's necessary to run
tox_install.sh if it exists as part of setup. We eventually want to make
that go away, but that's a different effort. There are seven repos with
a problematic tox_install.sh - patches will be arriving to fix them, and
we won't land the build-openstack-sphinx-docs changes until they have
all landed.
We've prepared these with a bunch of depends-on patches across a
collection of projects, so we don't anticipate much in the way of pain
... but life happens, so if you notice anything go south with
releasenotes or sphinx jobs, please let us know and we can help solve
any issues.
Thanks!
Monty
[0] https://review.openstack.org/#/c/509868
[1] https://review.openstack.org/#/c/508694
[2]
https://governance.openstack.org/tc/reference/project-testing-interface.html
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [email protected]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
