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

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

[Jani Nikula]

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
[1].

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

---

This is something I wrote two years ago, ISTR David asking about
something like this on IRC, but I've already forgotten what it was
about...
---
 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 bab3d0d286ce..95df9ae82b4f 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.
+TAGS := HAVE_XAPIAN_FIELD_PROCESSOR HAVE_XAPIAN_COMPACT
+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 f7a39ceb9df4..4840f03743aa 100644
--- a/doc/man7/notmuch-search-terms.rst
+++ b/doc/man7/notmuch-search-terms.rst
@@ -451,6 +451,14 @@ notmuch was built against a sufficiently recent version of Xapian by running
 
   % notmuch config get built_with.field_processor
 
+.. only:: HAVE_XAPIAN_FIELD_PROCESSOR
+
+   The documentation was built on a host with field processor support.
+
+.. only:: not HAVE_XAPIAN_FIELD_PROCESSOR
+
+   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"
-- 
2.20.1

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

[David Bremner]

Jani Nikula <jani@nikula.org> writes:

> 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
> [1].
>
> 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
>
> ---
>
> This is something I wrote two years ago, ISTR David asking about
> something like this on IRC, but I've already forgotten what it was
> about...

The urgent-ish issue is getting the docs building without
emacs. Hopefully similar technology can comment out the emacs docs from
the sphinx index page?

d

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

[David Bremner]

Jani Nikula <jani@nikula.org> writes:

> 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
> [1].
>
> 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
>
> ---
>
> This is something I wrote two years ago, ISTR David asking about
> something like this on IRC, but I've already forgotten what it was
> about...
> ---
>  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 bab3d0d286ce..95df9ae82b4f 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.
> +TAGS := HAVE_XAPIAN_FIELD_PROCESSOR HAVE_XAPIAN_COMPACT

Is there a good reason TAGS not defined in Makefile.config? Or just a
lack of tuits?

d

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

[David Bremner]

Jani Nikula <jani@nikula.org> writes:

>
> This is something I wrote two years ago, ISTR David asking about
> something like this on IRC, but I've already forgotten what it was
> about...

I (somewhere) have a patch for configure that generates the appropriate
tags. OTOH, the fact the tags can't be used to disable include files
(apparently the include is processed first, surprising almost everyone)
makes me less enthusiastic about this. Also, I hope soon to migrate
notmuch from xapian 1.2-1.4 to xapian 1.4-1.6, so everything will have
field processors.

d