Open Stack

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