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
signature.asc
Description: Digital signature
__________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
