[PATCH 1/2] doc: pass specified configure options as tags to Sphinx

[PATCH 1/2] doc: pass specified configure options as tags to Sphinx

[Jani Nikula]

Add generic support for passing enabled configure options as tags to
Sphinx. Add TAGS make variable to specify the configure options, and
use the sphinx-build -t option to add the options equal to 1 as tags.

The tags may be used in conf.py to conditionally adjust the
configuration [1], and to conditionally include content blocks in rst
files using the Sphinx "only" directive [2].

Initially, convert WITH_EMACS to a tag.

[1] https://www.sphinx-doc.org/en/master/usage/configuration.html#conf-tags
[2] https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#tags
---
 doc/Makefile.local | 9 +++++++--
 doc/conf.py        | 2 +-
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/doc/Makefile.local b/doc/Makefile.local
index b4e0c9558101..c78aea49a108 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -4,11 +4,16 @@ dir := doc
 
 # You can set these variables from the command line.
 SPHINXOPTS    := -q
-SPHINXBUILD   = WITH_EMACS=${WITH_EMACS} sphinx-build
+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 := WITH_EMACS
+TAGOPTS := $(patsubst %=1,-t %,$(filter %=1,$(foreach tag,$(TAGS),$(tag)=$(value $(tag)))))
+
 # Internal variables.
-ALLSPHINXOPTS   := $(SPHINXOPTS) $(srcdir)/$(dir)
+ALLSPHINXOPTS   := $(SPHINXOPTS) $(TAGOPTS) $(srcdir)/$(dir)
 APIMAN		:= $(DOCBUILDDIR)/man/man3/notmuch.3
 DOXYFILE	:= $(srcdir)/$(dir)/doxygen.cfg
 
diff --git a/doc/conf.py b/doc/conf.py
index fc9738ff092a..2ee063d77f10 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -32,7 +32,7 @@ exclude_patterns = ['_build']
 # If we don't have emacs (or the user configured --without-emacs),
 # don't build the notmuch-emacs docs, as they need emacs to generate
 # the docstring include files
-if os.environ.get('WITH_EMACS') != '1':
+if not tags.has('WITH_EMACS'):
     exclude_patterns.append('notmuch-emacs.rst')
 
 # The name of the Pygments (syntax highlighting) style to use.
-- 
2.20.1

[PATCH 2/2] doc: add a hint about field processor support availability

[Jani Nikula]

In most cases the documentation and the notmuch binary will be built
on the same machine and the same dependencies. Hint at the field
processor support availability in the man page based on the
documentation build host.
---
 doc/Makefile.local                | 2 +-
 doc/man7/notmuch-search-terms.rst | 8 ++++++++
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/doc/Makefile.local b/doc/Makefile.local
index c78aea49a108..cb01306c0b7c 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -9,7 +9,7 @@ DOCBUILDDIR      := $(dir)/_build
 
 # Configure options to be added as Sphinx tags.
 # Add "-t <tag>" for each make variable in TAGS that equals 1.
-TAGS := WITH_EMACS
+TAGS := WITH_EMACS HAVE_XAPIAN_FIELD_PROCESSOR
 TAGOPTS := $(patsubst %=1,-t %,$(filter %=1,$(foreach tag,$(TAGS),$(tag)=$(value $(tag)))))
 
 # Internal variables.
diff --git a/doc/man7/notmuch-search-terms.rst b/doc/man7/notmuch-search-terms.rst
index 1dd2dc5813f5..9e3b9398c58d 100644
--- a/doc/man7/notmuch-search-terms.rst
+++ b/doc/man7/notmuch-search-terms.rst
@@ -457,6 +457,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 2/2] doc: add a hint about field processor support availability

[Tomi Ollila]

On Sat, Jan 11 2020, Jani Nikula wrote:

> In most cases the documentation and the notmuch binary will be built
> on the same machine and the same dependencies. Hint at the field
> processor support availability in the man page based on the
> documentation build host.

I have to still grasp the TAGOPTS line in previous and this message =D

But, if we already made Xapian 1.4 minimun requirement in the next notmuch
release, there XAPIAN_FIELD_PROCESSOR is always supported and all these
conditionals could be removed (before even adding new)...

Tomi

> ---
>  doc/Makefile.local                | 2 +-
>  doc/man7/notmuch-search-terms.rst | 8 ++++++++
>  2 files changed, 9 insertions(+), 1 deletion(-)
>
> diff --git a/doc/Makefile.local b/doc/Makefile.local
> index c78aea49a108..cb01306c0b7c 100644
> --- a/doc/Makefile.local
> +++ b/doc/Makefile.local
> @@ -9,7 +9,7 @@ DOCBUILDDIR      := $(dir)/_build
>  
>  # Configure options to be added as Sphinx tags.
>  # Add "-t <tag>" for each make variable in TAGS that equals 1.
> -TAGS := WITH_EMACS
> +TAGS := WITH_EMACS HAVE_XAPIAN_FIELD_PROCESSOR
>  TAGOPTS := $(patsubst %=1,-t %,$(filter %=1,$(foreach tag,$(TAGS),$(tag)=$(value $(tag)))))
>  
>  # Internal variables.
> diff --git a/doc/man7/notmuch-search-terms.rst b/doc/man7/notmuch-search-terms.rst
> index 1dd2dc5813f5..9e3b9398c58d 100644
> --- a/doc/man7/notmuch-search-terms.rst
> +++ b/doc/man7/notmuch-search-terms.rst
> @@ -457,6 +457,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
>
> _______________________________________________
> notmuch mailing list
> notmuch@notmuchmail.org
> https://notmuchmail.org/mailman/listinfo/notmuch

Re: [PATCH 2/2] doc: add a hint about field processor support availability

[Daniel Kahn Gillmor]

[-- Attachment #1: Type: text/plain, Size: 636 bytes --]

On Sun 2020-01-12 17:13:59 +0200, Tomi Ollila wrote:
> But, if we already made Xapian 1.4 minimun requirement in the next notmuch
> release, there XAPIAN_FIELD_PROCESSOR is always supported and all these
> conditionals could be removed (before even adding new)...

I'd support making Xapian 1.4 a minimum requirement in the next notmuch
release, particularly if someone does the work to provide a mostly-minus
patchset that cleans up the legacy conditionals.

fwiw, xapian 1.4 was part of debian oldstable (stretch), which was
released in mid-2017.  I don't think it's a problem to require a
dependency of that vintage.

         --dkg

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]