[RFC PATCH] doc: add support for adding configure options as Sphinx tags

Jani Nikula jani at nikula.org
Sun Feb 26 12:56:57 PST 2017

Add the configure options specified in $(TAGS) that equal 1 as tags on
the Sphinx command line using the -t option. The tags may be used to
conditionally include documentation using the Sphinx "only" directive

As an example, indicate in the documentation whether the Xapian field
processor is likely to be available (assuming the notmuch binary was
built in the same environment as the documentation).

[1] http://www.sphinx-doc.org/en/stable/markup/misc.html#including-content-based-on-tags


Just an idea, not sure if it makes sense.
 doc/Makefile.local                | 7 ++++++-
 doc/man7/notmuch-search-terms.rst | 8 ++++++++
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/doc/Makefile.local b/doc/Makefile.local
index c6f05ca879c0..24fc457cab14 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -7,8 +7,13 @@ SPHINXOPTS    := -q
 SPHINXBUILD   = sphinx-build
 DOCBUILDDIR      := $(dir)/_build
+# Configure options to be added as Sphinx tags.
+# Add "-t <tag>" for each make variable in TAGS that equals 1.
+TAGOPTS := $(patsubst %=1,-t %,$(filter %=1,$(foreach tag,$(TAGS),$(tag)=$(value $(tag)))))
 # Internal variables.
-ALLSPHINXOPTS   := -d $(DOCBUILDDIR)/doctrees $(SPHINXOPTS) $(srcdir)/$(dir)
+ALLSPHINXOPTS   := -d $(DOCBUILDDIR)/doctrees $(SPHINXOPTS) $(TAGOPTS) $(srcdir)/$(dir)
 APIMAN		:= $(DOCBUILDDIR)/man/man3/notmuch.3
 DOXYFILE	:= $(srcdir)/$(dir)/doxygen.cfg
diff --git a/doc/man7/notmuch-search-terms.rst b/doc/man7/notmuch-search-terms.rst
index de93d7332472..0a2f74ce57a6 100644
--- a/doc/man7/notmuch-search-terms.rst
+++ b/doc/man7/notmuch-search-terms.rst
@@ -392,6 +392,14 @@ notmuch was built against a sufficiently recent version of Xapian by running
   % notmuch config get built_with.field_processor
+   The documentation was built on a host with field processor support.
+   The documentation was built on a host without field processor support.
 Currently the following features require field processor support:
 - non-range date queries, e.g. "date:today"

More information about the notmuch mailing list