Use separate sphinx-build cache directories

Simultaneously starting multiple sphinx-build instances with the -d
command line switch set to a common value (which is what happens when
e.g. "make -j6 doc" is run) causes intermittent problems which we failed
to notice before because they only trigger Sphinx warnings, not errors,
e.g.:

    WARNING: toctree contains ref to nonexisting file 'reference'

The message above is not triggered because doc/arm/reference.rst is
actually missing from disk at any point, but rather because a temporary
file created by one sphinx-build instance gets truncated by another one
working in parallel (the confusing message quoted above is logged
because of an overly broad "except" statement in Sphinx code).

Prevent this problem from being triggered by making each sphinx-build
process use its own dedicated cache directory.

diff --git a/doc/arm/Makefile.am b/doc/arm/Makefile.am
index 26b64f723145281e310c82a9334d31a84e2d12df..31a06ebd297e147c15e69b7c67c4ad13b270bfa0 100644 (file)
--- a/doc/arm/Makefile.am
+++ b/doc/arm/Makefile.am
@@ -48,7 +48,7 @@ EXTRA_DIST =                                  \
        ../notes/*.rst
 
 html-local:
-       $(AM_V_SPHINX)$(SPHINX_BUILD) -b html -d $(SPHINXBUILDDIR)/doctrees $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/html
+       $(AM_V_SPHINX)$(SPHINX_BUILD) -b html -d $(SPHINXBUILDDIR)/.doctrees/html $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/html
 
 install-html-local:
        $(INSTALL) -d $(DESTDIR)/$(docdir) $(DESTDIR)/$(docdir)/_static
@@ -56,7 +56,7 @@ install-html-local:
        cp -R $(SPHINXBUILDDIR)/html/_static/ $(DESTDIR)/$(docdir)/_static/
 
 singlehtml:
-       $(AM_V_SPHINX)$(SPHINX_BUILD) -b singlehtml -d $(SPHINXBUILDDIR)/doctrees $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/singlehtml
+       $(AM_V_SPHINX)$(SPHINX_BUILD) -b singlehtml -d $(SPHINXBUILDDIR)/.doctrees/singlehtml $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/singlehtml
 
 install-singlehtml: singlehtml
        $(INSTALL) -d $(DESTDIR)/$(docdir) $(DESTDIR)/$(docdir)/_static
@@ -64,7 +64,7 @@ install-singlehtml: singlehtml
        cp -R $(SPHINXBUILDDIR)/singlehtml/_static/* $(DESTDIR)/$(docdir)/_static/
 
 epub:
-       $(AM_V_SPHINX)$(SPHINX_BUILD) -b epub -A today=$(RELEASE_DATE) -d $(SPHINXBUILDDIR)/doctrees $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/epub
+       $(AM_V_SPHINX)$(SPHINX_BUILD) -b epub -A today=$(RELEASE_DATE) -d $(SPHINXBUILDDIR)/.doctrees/epub $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/epub
 
 install-epub:
        $(INSTALL) -d $(DESTDIR)/$(docdir)
@@ -72,7 +72,7 @@ install-epub:
 
 if HAVE_XELATEX
 pdf-local:
-       $(AM_V_SPHINX)$(SPHINX_BUILD) -b latex -d $(SPHINXBUILDDIR)/doctrees $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/latex
+       $(AM_V_SPHINX)$(SPHINX_BUILD) -b latex -d $(SPHINXBUILDDIR)/.doctrees/latex $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/latex
        $(MAKE) -C $(SPHINXBUILDDIR)/latex all-pdf
 
 install-pdf-local:

diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am
index f11a46fd823bf2dc3aeee62868f224732843e73b..d363e35355691a26c06bc5f0f7a337b5015ffd4a 100644 (file)
--- a/doc/man/Makefile.am
+++ b/doc/man/Makefile.am
@@ -169,7 +169,7 @@ if HAVE_SPHINX_BUILD
 manpages.stamp: $(MANPAGES_RST)
        @rm -f manpages.tmp
        @touch manpages.tmp
-       $(AM_V_SPHINX)$(SPHINX_BUILD) -b man -d $(SPHINXBUILDDIR)/doctrees $(man_SPHINXOPTS) $(SPHINXBUILDDIR)/man
+       $(AM_V_SPHINX)$(SPHINX_BUILD) -b man -d $(SPHINXBUILDDIR)/.doctrees/man $(man_SPHINXOPTS) $(SPHINXBUILDDIR)/man
        for f in $(SPHINXBUILDDIR)/man/*; do \
          cp -a "$$f" "$(srcdir)/$$(basename $$f)in"; \
        done