From 33db7ea16d630b3fcc756c704b1a91ae887019f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20K=C4=99pie=C5=84?= Date: Wed, 3 Feb 2021 11:44:02 +0100 Subject: [PATCH 1/3] 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. --- doc/arm/Makefile.am | 8 ++++---- doc/man/Makefile.am | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/arm/Makefile.am b/doc/arm/Makefile.am index 26b64f7231..31a06ebd29 100644 --- 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 f11a46fd82..d363e35355 100644 --- 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 From 84862e96c1fcff6e7c1ca31884e2fad921afa4f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20K=C4=99pie=C5=84?= Date: Wed, 3 Feb 2021 11:44:02 +0100 Subject: [PATCH 2/3] Address a Sphinx duplicate label warning Both doc/man/ddns-confgen.rst and doc/man/tsig-keygen.rst include bin/confgen/tsig-keygen.rst, which defines a "man_tsig-keygen" label. This triggers the following warning when running sphinx-build with the -W command line switch in the doc/man/ directory: ../../bin/confgen/tsig-keygen.rst:27: WARNING: duplicate label man_tsig-keygen, other instance in /tmp/bind9/doc/man/ddns-confgen.rst Move the offending label from bin/confgen/tsig-keygen.rst to the proper spot in doc/arm/manpages.rst to avoid effectively defining it twice in different source documents while still allowing the relevant man page to be referenced in the ARM. Also rename that label so that it more closely matches the content it points to. As the label no longer immediately precedes a section title in its new location, use :ref:`Title