On Tue, 2017-03-14 at 10:50 -0400, Russell Bryant wrote: > On Tue, Mar 14, 2017 at 8:21 AM, Stephen Finucane <step...@that.guru> > wrote: > > On Mon, 2017-03-13 at 17:41 -0400, Russell Bryant wrote: > > > There have been a few patches lately tweaking docs to deal with > > > different > > > sphinx versions in different linux distributions. This patch > > > demonstrates > > > an alternative approach to avoid those types of issues. Instead > > > of > > > calling > > > sphinx-build directly, it uses tox to build a Python virtual > > > environment > > > based on the requirements.txt file. Everyone would have to > > > install > > > tox, > > > but then everyone would automatically use the same versions of > > > doc > > > build > > > dependencies. > > > TODO: > > > - remove checking for sphinx from build system, add tox check > > > instead > > > - update various documentations to reflect that you should > > > install > > > tox > > > > > > Signed-off-by: Russell Bryant <russ...@ovn.org> > > > > I'm on the fence with this. On one hand, I myself used a virtualenv > > to > > develop the docs to make sure I had the latest and greatest Sphinx > > version and to avoid cluttering my system PYTHONPATH. However, > > something about calling tox from make seems...icky :) I like tox, > > but > > it does seem like something that doesn't belong in a C-based > > project. > > > > I'm pretty sure I noted the option of using virtualenv when > > building > > docs, so we could just update the sphinx version check to check a > > given > > pygments version too. Anyone that can't match that with system > > packages > > (Ubuntu 14.04, for example) would be advised to use virtualenvs. > > > > The above is entirely subjective though, and I've no strong > > technical > > reason not to follow through with the tox approach. If Ben et al > > are > > happy with this, then so am I. > > I suppose another option would be to have this available, but not run > by make. We can document that if you have trouble with using sphinx > directly, you can re-run configure --without-sphinx and then run tox > manually to build the docs.
So keep make as-is and provide tox as an alternative? I would prefer this, yes. We could still highlight the virtualenv instructions for people that wish to use make too. We could also do as someone suggested and just remove all 'code-block' directives, removing any reliance on Pygments (which seems to be the main culprit here). Syntax highlighting is nice, but a simpler build is perhaps nicer. Stephen _______________________________________________ dev mailing list d...@openvswitch.org https://mail.openvswitch.org/mailman/listinfo/ovs-dev
