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>
---
.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.
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}
--
2.9.3
_______________________________________________
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev
