Open Stack

On 2017-07-07 18:03:11 -0500 (-0500), Monty Taylor wrote:
> On 07/07/2017 12:12 PM, Jeremy Stanley wrote:
[...]
> > 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'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.
[...]

Sure, I agree that the tox invocation is more of an implementation
detail. My concern is over making sure that projects don't each end
up with their own bespoke docs building process behind some opaque
entrypoint on which we've standardized. If we simply say `tox -e
docs` is required then we'll end up with a number of projects
calling wrapper scripts from that which do all manner of badness
before (hopefully still at least) invoking sphinx-build. Sphinx
already provides turing-complete flexibility on its own, so when
fancy features are required we should do that by improving themes
and adding plugins rather than through random hacky wrapper scripts.

The detailed plan you outlined in your message (elided for the sake
of brevity) seems fine to me. Thanks!
-- 
Jeremy Stanley
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 949 bytes
Desc: Digital signature
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20170708/41e02a13/attachment.sig>