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.
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
