Open Stack

On 07/07/2017 12:12 PM, Jeremy Stanley wrote:
> On 2017-07-07 11:20:30 -0400 (-0400), Doug Hellmann wrote:
> [...]
>> We also discussed changing the CI interface to build docs to use
>> the "tox -e docs" command like contributors generally run locally.
> [...]
> 
> Better still, something like `tox -e venv -- sphinx-build` would be
> more in keeping with the spirit of the PTI to ensure projects don't
> encapsulate any secret sauce into a separate "docs" tox env and so
> can have their documentation built correctly via a more standard
> (for the Python ecosystem) command line.

I've been thinking about this a bunch recently as I've been working on 
zuul v3 versions of our base jobs with an eye on them being sharable 
between installations.

I'm starting to be of the opinion that we may be stretching things a 
little far with the tox -evenv -- in this case and making it harder not 
easier.

I'd like to suggest a few different things:

a) We define what we think the correct sphinx-build invocation is, 
regardless of tox/make/venv/etc. and define that in the PTI. Sphinx is 
perfectly usable for docs for other languages too, so having a standard 
"we expect sphinx-build to work right" (if that's the right invocation) 
seems like a better long-term win.

b) Update the PTI to indicate that a tox.ini needs to have a venv env 
that supports arbitrary commands, regardless of which commands.

c) Split docs/sphinx requirements from test-requirements.txt to 
docs-requirements.txt. This is potentially useful in in two ways:

* Because we only have 'test-requirements.txt', it gets installs for all 
the things. But you know what- docutils is actually not needed to run 
unittests. So in many cases it should trim venv size.

* In non-python projects, putting a docs-requirements.txt there even if 
there is not a similar requirements.txt or test-requirements.txt seems 
reasonable. At worst it's just a text file that indicates you need to 
install some python things to make docs building work and a human can 
figure that out.

Then the CI job could be:

if [ -f tox.ini ] ; then
   tox -evenv -- sphinx-build
else if [ -f docs-requirements.txt ] ; then
   pip install -edocs-requirements.txt
   sphinx-build
else
   sphinx-build
fi

And it should cover a lot of the cases, plus building docs locally 
should continue to work sanely.