[openstack-dev] [all] Changes to releasenotes and docs build jobs

Andreas Jaeger aj at suse.com
Sat Dec 9 14:37:10 UTC 2017

On 11/22/2017 07:39 AM, Monty Taylor wrote:
> 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

The majority of the changes for this have merged, let's move forward:


> * 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.

For many projects, tox_install.sh is not needed at all and can be easily 
replaced. Changes are up for those that we can replace easily - and many 
are already merged. For open changes, see


Please review and merge,


> 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: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
    GF: Felix Imendörffer, Jane Smithard, Graham Norton,
        HRB 21284 (AG Nürnberg)
     GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126

More information about the OpenStack-dev mailing list