[PATCH 1/4] doc: don't attempt to build info pages if Emacs is missing.

[PATCH 1/4] doc: don't attempt to build info pages if Emacs is missing.

[David Bremner]

This is a sledgehammer approach to conditionally (not) build the
notmuch-emacs documentation, since it is currently the only thing that
needs Emacs to build.  Hopefully in the future we can come up with a
cleaner way of disabling building the notmuch-emacs docs when emacs is
missing.
---
 doc/Makefile.local | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/Makefile.local b/doc/Makefile.local
index dfe62295..c148d74a 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -116,14 +116,14 @@ install-man: ${MAN_GZIP_FILES}
 	cd $(DESTDIR)/$(mandir)/man1 && ln -sf notmuch.1.gz notmuch-setup.1.gz
 endif
 
-ifneq ($(HAVE_SPHINX)$(HAVE_MAKEINFO),11)
+ifneq ($(HAVE_SPHINX)$(HAVE_MAKEINFO)$(HAVE_EMACS),111)
 build-info:
-	@echo "Missing sphinx or makeinfo, not building info pages"
+	@echo "Missing prerequisites, not building info pages"
 else
 build-info: sphinx-info
 endif
 
-ifneq ($(HAVE_SPHINX)$(HAVE_MAKEINFO)$(HAVE_INSTALL_INFO),111)
+ifneq ($(HAVE_SPHINX)$(HAVE_MAKEINFO)$(HAVE_INSTALL_INFO)$(HAVE_EMACS),1111)
 install-info:
 	@echo "Missing prerequisites, not installing info pages"
 else
-- 
2.20.1

[PATCH 2/4] doc: use stamp file to control rebuilding texi

[David Bremner]

Apparently the sphinx-doc texinfo builder is not smart enough to only
rebuild those files where the source has changed.
---
 doc/Makefile.local | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/doc/Makefile.local b/doc/Makefile.local
index c148d74a..2a701646 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -16,6 +16,7 @@ MAN1_RST := $(wildcard $(srcdir)/doc/man1/*.rst)
 MAN5_RST := $(wildcard $(srcdir)/doc/man5/*.rst)
 MAN7_RST := $(wildcard $(srcdir)/doc/man7/*.rst)
 MAN_RST_FILES := $(MAN1_RST) $(MAN5_RST) $(MAN7_RST)
+ALL_RST_FILES := $(MAN_RST_FILES) $(srcdir)/doc/notmuch-emacs.rst
 
 MAN1_ROFF := $(patsubst $(srcdir)/doc/%,$(DOCBUILDDIR)/man/%,$(MAN1_RST:.rst=.1))
 MAN5_ROFF := $(patsubst $(srcdir)/doc/%,$(DOCBUILDDIR)/man/%,$(MAN5_RST:.rst=.5))
@@ -52,8 +53,11 @@ sphinx-info: | sphinx-texinfo
 sphinx-html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DOCBUILDDIR)/html
 
-sphinx-texinfo:
+sphinx-texinfo: .texi.stamp
+
+$(DOCBUILDDIR)/.texi.stamp: $(ALL_RST_FILES)
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(DOCBUILDDIR)/texinfo
+	touch $@
 
 sphinx-info: sphinx-texinfo
 	$(MAKE) -C $(DOCBUILDDIR)/texinfo info
@@ -137,5 +141,5 @@ $(dir)/config.dox: version.stamp
 	echo "PROJECT_NAME = \"Notmuch $(VERSION)\"" > $@
 	echo "INPUT=${srcdir}/lib/notmuch.h" >> $@
 
-CLEAN := $(CLEAN) $(DOCBUILDDIR) $(DOCBUILDDIR)/.roff.stamp
+CLEAN := $(CLEAN) $(DOCBUILDDIR) $(DOCBUILDDIR)/.roff.stamp $(DOCBUILDDIR)/.texi.stamp
 CLEAN := $(CLEAN) $(MAN_GZIP_FILES) $(MAN_ROFF_FILES) $(dir)/conf.pyc $(dir)/config.dox
-- 
2.20.1

[PATCH 3/4] doc: use stamp file for html docs

[David Bremner]

These are less time consuming than the texi docs to rebuild (because
the texi rebuild triggers info rebuild), but still take noticable time.
---
 doc/Makefile.local | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/doc/Makefile.local b/doc/Makefile.local
index 2a701646..a8fee537 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -50,10 +50,13 @@ sphinx-html: | $(DOCBUILDDIR)/.roff.stamp
 sphinx-texinfo: | sphinx-html
 sphinx-info: | sphinx-texinfo
 
-sphinx-html:
+sphinx-html: $(DOCBUILDDIR)/.html.stamp
+
+$(DOCBUILDDIR)/.html.stamp: $(ALL_RST_FILES)
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DOCBUILDDIR)/html
+	touch $@
 
-sphinx-texinfo: .texi.stamp
+sphinx-texinfo: $(DOCBUILDDIR)/.texi.stamp
 
 $(DOCBUILDDIR)/.texi.stamp: $(ALL_RST_FILES)
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(DOCBUILDDIR)/texinfo
@@ -142,4 +145,5 @@ $(dir)/config.dox: version.stamp
 	echo "INPUT=${srcdir}/lib/notmuch.h" >> $@
 
 CLEAN := $(CLEAN) $(DOCBUILDDIR) $(DOCBUILDDIR)/.roff.stamp $(DOCBUILDDIR)/.texi.stamp
+CLEAN := $(CLEAN) $(DOCBUILDDIR)/.html.stamp
 CLEAN := $(CLEAN) $(MAN_GZIP_FILES) $(MAN_ROFF_FILES) $(dir)/conf.pyc $(dir)/config.dox
-- 
2.20.1

[PATCH 4/4] build: ignore *.stamp

[David Bremner]

The current case is docstring.stamp, but it's likely that others will
arise.
---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitignore b/.gitignore
index e06101ce..468b660a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,3 +15,4 @@ tags
 .*.swp
 /releases
 /.stamps
+*.stamp
-- 
2.20.1

Re: [PATCH 1/4] doc: don't attempt to build info pages if Emacs is missing.

[David Bremner]

David Bremner <david@tethera.net> writes:

> This is a sledgehammer approach to conditionally (not) build the
> notmuch-emacs documentation, since it is currently the only thing that
> needs Emacs to build.  Hopefully in the future we can come up with a
> cleaner way of disabling building the notmuch-emacs docs when emacs is
> missing.

This is not enough, but itself, as docstrings.stamp also needs to be
special cased. And that still leaves a bunch of ugly warnings and errors
when building the man pages. So I probably need to rething this patch.

[PATCH 1/2] build: only try to build .rsti files if we have emacs and sphinx

[David Bremner]

Emacs is needed to build them, and sphinx is needed to use them
---
 emacs/Makefile.local | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/emacs/Makefile.local b/emacs/Makefile.local
index 04913a06..40b7c14f 100644
--- a/emacs/Makefile.local
+++ b/emacs/Makefile.local
@@ -47,8 +47,13 @@ emacs_images := \
 emacs_bytecode = $(emacs_sources:.el=.elc)
 emacs_docstrings = $(emacs_sources:.el=.rsti)
 
+ifneq ($(HAVE_SPHINX)$(HAVE_EMACS),11)
+docstring.stamp:
+	@echo "Missing prerequisites, not collecting docstrings"
+else
 docstring.stamp: ${emacs_docstrings}
 	touch $@
+endif
 
 # Because of defmacro's and defsubst's, we have to account for load
 # dependencies between Elisp files when byte compiling.  Otherwise,
-- 
2.20.1

[PATCH 2/2] doc: exclude notmuch-emacs.rst if emacs is not present.

[David Bremner]

This will still generate a warning about an excluded document in the
toctree, but it cuts down on the noise quite a lot.
---
 doc/Makefile.local | 2 +-
 doc/conf.py        | 5 +++++
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/doc/Makefile.local b/doc/Makefile.local
index 57104dae..651168f4 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -4,7 +4,7 @@ dir := doc
 
 # You can set these variables from the command line.
 SPHINXOPTS    := -q
-SPHINXBUILD   = sphinx-build
+SPHINXBUILD   = HAVE_EMACS=${HAVE_EMACS} sphinx-build
 DOCBUILDDIR      := $(dir)/_build
 
 # Internal variables.
diff --git a/doc/conf.py b/doc/conf.py
index 0ef72327..5f8c9f1c 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -29,6 +29,11 @@ release = version
 # directories to ignore when looking for source files.
 exclude_patterns = ['_build']
 
+# If we don't have emacs, don't build the notmuch-emacs docs, as they need
+# emacs to generate the docstring include files
+if os.environ.get('HAVE_EMACS') != '1':
+    exclude_patterns.append('notmuch-emacs.rst')
+
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
-- 
2.20.1

Re: [PATCH 3/4] doc: use stamp file for html docs

[Daniel Kahn Gillmor]

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

On Sun 2019-04-21 14:12:44 -0300, David Bremner wrote:
> These are less time consuming than the texi docs to rebuild (because
> the texi rebuild triggers info rebuild), but still take noticable time.
> ---
>  doc/Makefile.local | 8 ++++++--
>  1 file changed, 6 insertions(+), 2 deletions(-)
>
> diff --git a/doc/Makefile.local b/doc/Makefile.local
> index 2a701646..a8fee537 100644
> --- a/doc/Makefile.local
> +++ b/doc/Makefile.local
> @@ -50,10 +50,13 @@ sphinx-html: | $(DOCBUILDDIR)/.roff.stamp
>  sphinx-texinfo: | sphinx-html
>  sphinx-info: | sphinx-texinfo
>  
> -sphinx-html:
> +sphinx-html: $(DOCBUILDDIR)/.html.stamp
> +
> +$(DOCBUILDDIR)/.html.stamp: $(ALL_RST_FILES)
>  	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DOCBUILDDIR)/html
> +	touch $@
>  
> -sphinx-texinfo: .texi.stamp
> +sphinx-texinfo: $(DOCBUILDDIR)/.texi.stamp

I think this final change (to the sphinx-texinfo target) belongs in the
previous patchset.

Otherwise, this series looks good to me, using your followup two-part
replacement for the obsolete 1/4 patch.

I've tested it, and it reduces the amount of time for the subsequent run
of "make" quite a bit.

After a "./configure && make clean && make", subsequent repeated "make
--trace" runs look like this:

0 dkg@alice:~/src/notmuch/notmuch$ make --trace
emacs/Makefile.local:76: update target 'emacs/.eldeps.x' due to: emacs/.eldeps
cmp -s emacs/.eldeps emacs/.eldeps.x || cp emacs/.eldeps emacs/.eldeps.x
doc/Makefile.local:66: update target 'sphinx-info' due to: sphinx-texinfo
make -C doc/_build/texinfo info
make[1]: Entering directory '/home/dkg/src/notmuch/notmuch/doc/_build/texinfo'
make[1]: Nothing to be done for 'info'.
make[1]: Leaving directory '/home/dkg/src/notmuch/notmuch/doc/_build/texinfo'
bindings/Makefile.local:8: update target 'ruby-bindings' due to: lib/libnotmuch.so
cd bindings/ruby && \
	EXTRA_LDFLAGS="-Wl,--no-undefined" \
	LIBNOTMUCH="../../lib/libnotmuch.so" \
	NOTMUCH_SRCDIR='/home/dkg/src/notmuch/notmuch' \
	ruby extconf.rb --vendor
creating Makefile
make -C bindings/ruby
make[1]: Entering directory '/home/dkg/src/notmuch/notmuch/bindings/ruby'
Makefile:258: update target 'notmuch.so' due to: Makefile
echo linking shared-object notmuch.so
linking shared-object notmuch.so
rm -f notmuch.so
gcc -shared -o notmuch.so database.o directory.o filenames.o init.o message.o messages.o query.o status.o tags.o thread.o threads.o -L. -L/usr/lib/x86_64-linux-gnu -L. -Wl,-z,relro -Wl,-z,now -fstack-protector -rdynamic -Wl,-export-dynamic -Wl,--no-undefined -Wl,-z,relro -Wl,-z,now -Wl,--compress-debug-sections=zlib   ../../lib/libnotmuch.so -lruby-2.5  -lpthread -lgmp -ldl -lcrypt -lm   -lc
make[1]: Leaving directory '/home/dkg/src/notmuch/notmuch/bindings/ruby'
0 dkg@alice:~/src/notmuch/notmuch$ 

so there's still a bit of strange .eldeps and sphinx-*info business, but
they take basically no time.  And of course the ruby bindings haven't
been dealt with yet.

This seems like a clear improvement on the status quo, so i think we
should merge it and whittle down the remaining issues where we can.

         --dkg

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

Re: [PATCH 3/4] doc: use stamp file for html docs

[David Bremner]

Daniel Kahn Gillmor <dkg@fifthhorseman.net> writes:

>>  
>> -sphinx-texinfo: .texi.stamp
>> +sphinx-texinfo: $(DOCBUILDDIR)/.texi.stamp
>
> I think this final change (to the sphinx-texinfo target) belongs in the
> previous patchset.
>
> Otherwise, this series looks good to me, using your followup two-part
> replacement for the obsolete 1/4 patch.
>

thanks for catching that. I've pushed the amended series.