| Message ID | 20170313214100.11753-1-russell@ovn.org |
|---|---|
| State | RFC |
| Headers | show |
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 <russell@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. Stephen
On Tue, Mar 14, 2017 at 8:21 AM, Stephen Finucane <stephen@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 <russell@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.
On Tue, 2017-03-14 at 10:50 -0400, Russell Bryant wrote: > On Tue, Mar 14, 2017 at 8:21 AM, Stephen Finucane <stephen@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 <russell@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
diff --git a/.gitignore b/.gitignore index 4f50440..4688708 100644 --- a/.gitignore +++ b/.gitignore @@ -30,6 +30,7 @@ .libs .tmp_versions .gitattributes +.tox /Makefile /Makefile.in /aclocal.m4 diff --git a/Documentation/automake.mk b/Documentation/automake.mk index 22a614b..ddaa9d8 100644 --- a/Documentation/automake.mk +++ b/Documentation/automake.mk @@ -91,14 +91,12 @@ EXTRA_DIST += \ # You can set these variables from the command line. SPHINXOPTS = -SPHINXBUILD = sphinx-build -SPHINXSRCDIR = $(srcdir)/Documentation + SPHINXBUILDDIR = $(builddir)/Documentation/_build # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -W -n -d $(SPHINXBUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SPHINXSRCDIR) sphinx_verbose = $(sphinx_verbose_@AM_V@) sphinx_verbose_ = $(sphinx_verbose_@AM_DEFAULT_V@) @@ -106,11 +104,11 @@ sphinx_verbose_0 = -q if HAVE_SPHINX htmldocs: - $(AM_V_GEN)$(SPHINXBUILD) $(sphinx_verbose) -b html $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/html + $(AM_V_GEN)tox -c $(srcdir)/tox.ini -e docs -- $(SPHINXBUILDDIR) $(sphinx_verbose) $(SPHINXOPTS) $(PAPEROPT_$(PAPER)) ALL_LOCAL += htmldocs check-docs: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/linkcheck + $(AM_V_GEN)tox -c $(srcdir)/tox.ini -e check-docs -- $(SPHINXBUILDDIR)/linkcheck $(sphinx_verbose) $(SPHINXOPTS) $(PAPEROPT_$(PAPER)) clean-docs: rm -rf $(SPHINXBUILDDIR)/doctrees diff --git a/Makefile.am b/Makefile.am index c853085..60e25fc 100644 --- a/Makefile.am +++ b/Makefile.am @@ -87,7 +87,8 @@ EXTRA_DIST = \ $(MAN_ROOTS) \ Vagrantfile \ Vagrantfile-FreeBSD \ - .mailmap + .mailmap \ + tox.ini bin_PROGRAMS = sbin_PROGRAMS = bin_SCRIPTS = diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..ee2a186 --- /dev/null +++ b/tox.ini @@ -0,0 +1,13 @@ +[tox] +envlist = docs +skipsdist = True + +[testenv] +deps = -r{toxinidir}/Documentation/requirements.txt +passenv = SPHINXBUILDDIR + +[testenv:docs] +commands = sphinx-build -b html -W -n -d _build/doctrees Documentation {posargs} + +[testenv:check-docs] +commands = sphinx-build -b linkcheck -W -n -d _build/doctrees Documentation {posargs}
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 <russell@ovn.org> --- .gitignore | 1 + Documentation/automake.mk | 8 +++----- Makefile.am | 3 ++- tox.ini | 13 +++++++++++++ 4 files changed, 19 insertions(+), 6 deletions(-) create mode 100644 tox.ini Works for me in very basic local testing. I figured I'd share the approach for general feedback before going and cleaning it up and adjusting docs.