From: "W. Trevor King" <wking@tremily.us>
To: notmuch@notmuchmail.org
Subject: [PATCH v2 4/5] doc: Consolidate Makefile targets around
	{build|install}-{format}
Date: Sat, 10 May 2014 10:03:35 -0700
Message-Id:
 <4fb5447805a8d5bb8da74c0196f12ac4ffaf4394.1399740604.git.wking@tremily.us>
In-Reply-To: <cover.1399740604.git.wking@tremily.us>
References: <cover.1399740604.git.wking@tremily.us>
In-Reply-To: <cover.1399740604.git.wking@tremily.us>
References: <cover.1399740604.git.wking@tremily.us>
Cc: Tomi Ollila <tomi.ollila@iki.fi>
Precedence: list

The rst2man target was removed in 9d9a700 (doc: build man pages at
build time; introduce HAVE_SPHINX, HAVE_RST2MAN, 2014-03-13), but a
reference in the install docs slipped through.  While I was removing
that reference, I also:

* Converted doc/INSTALL to reStructuredText, so I can link to Sphinx
  and Docutils directly.  Not everyone has access to Debian's
  python-docutils, so it's better to be genric here.
* Converted from an unordered list to paragraphs, because I think it
  flows better.
* Dropped the rst2man no-automatic-install caveat.  I don't think this
  applies to the current code, although I haven't tried to track down
  a commit that adds the automatic-install support.  Anyhow,

    $ make HAVE_SPHINX=0 HAVE_RST2MAN=1 RST2MAN=rst2man.py DESTDIR=/tmp/ install-man

  works for me.
* Restructured the Makefile to use build- and install- prefixes
  consistently, regardless of Sphinx/rst2x backend.
* Instead of disabling the build-man and install-man targets if
  HAVE_SPHINX and HAVE_RST2MAN are both empty, just pull build-man and
  install-man out of the default build tree.  That way:

    $ make HAVE_SPHINX=0 HAVE_RST2MAN=0 build-man

  will fail like it should, instead of successfully doing nothing.  If
  packagers *do* want to force building the docs, despite any config
  settings, you can override the BUILD_MAN and INSTALL_MAN variables:

    $ make BUILD_MAN=build-man all
---
 Makefile.local     | 14 ++++++++++++--
 doc/INSTALL        | 44 ++++++++++++++++++++++++++++++--------------
 doc/Makefile.local | 42 ++++++++++++++++++++++++------------------
 3 files changed, 66 insertions(+), 34 deletions(-)

diff --git a/Makefile.local b/Makefile.local
index fa07d81..83984fd 100644
--- a/Makefile.local
+++ b/Makefile.local
@@ -43,6 +43,15 @@ GPG_FILE=$(SHA1_FILE).asc
 
 PV_FILE=bindings/python/notmuch/version.py
 
+# Disable docs if we don't have the builders
+ifeq ($(HAVE_SPHINX)$(HAVE_RST2MAN),00)
+BUILD_MAN =
+INSTALL_MAN =
+else
+BUILD_MAN = build-man
+INSTALL_MAN = install-man
+endif
+
 # Smash together user's values with our extra values
 FINAL_CFLAGS = -DNOTMUCH_VERSION=$(VERSION) $(CPPFLAGS) $(CFLAGS) $(WARN_CFLAGS) $(extra_cflags) $(CONFIGURE_CFLAGS)
 FINAL_CXXFLAGS = $(CPPFLAGS) $(CXXFLAGS) $(WARN_CXXFLAGS) $(extra_cflags) $(extra_cxxflags) $(CONFIGURE_CXXFLAGS)
@@ -58,7 +67,7 @@ endif
 FINAL_LIBNOTMUCH_LDFLAGS = $(LDFLAGS) $(AS_NEEDED_LDFLAGS) $(CONFIGURE_LDFLAGS)
 
 .PHONY: all
-all: notmuch notmuch-shared build-man
+all: notmuch notmuch-shared $(BUILD_MAN)
 ifeq ($(MAKECMDGOALS),)
 ifeq ($(shell cat .first-build-message 2>/dev/null),)
 	@NOTMUCH_FIRST_BUILD=1 $(MAKE) --no-print-directory all
@@ -299,7 +308,8 @@ notmuch-shared: $(notmuch_client_modules) lib/$(LINKER_NAME)
 	$(call quiet,$(FINAL_NOTMUCH_LINKER) $(CFLAGS)) $(notmuch_client_modules) $(FINAL_NOTMUCH_LDFLAGS) -o $@
 
 .PHONY: install
-install: all install-man
+
+install: all $(INSTALL_MAN)
 	mkdir -p "$(DESTDIR)$(prefix)/bin/"
 	install notmuch-shared "$(DESTDIR)$(prefix)/bin/notmuch"
 ifeq ($(MAKECMDGOALS), install)
diff --git a/doc/INSTALL b/doc/INSTALL
index e37c2b9..8352f7b 100644
--- a/doc/INSTALL
+++ b/doc/INSTALL
@@ -1,24 +1,40 @@
+.. -*- rst -*-
+
 This file contains some more detailed information about building and
 installing the documentation.
 
-Building with sphinx.
----------------------
+Building with Sphinx
+--------------------
 
-- You need sphinx at least version 1.0.
+With Sphinx_ version 1.0 or greater, you can build HTML, man, and info
+versions of the documentation with::
 
-- You can build build and install man pages with 'make install-man'
+  make build-{html|info|man}
 
-- You can build man, info, html, and pdf versions of the docs
-  (currently only the man pages) with
+You can build and install the documentation with::
 
-     'make install-{man|info|html|pdf}'
+  make install-{info|man}
 
-Building the man pages
+Building with Docutils
 ----------------------
 
-- You can build the man pages with rst2man (from python-docutils) with
-  'make rst2man'.
-
-- Currently there is no support to automagically install the resulting
-  nroff files, but it should work to modify the target install-man
-  in doc/Makefile.local.
+If you don't have Sphinx installed, you can use Docutils_ with the
+same targets outlined above for Sphinx.  The Docutils converters
+(rst2man, rst2html, etc.) are used instead of Sphinx.  Only the man
+targets are currently supported.
+
+Configuring the builder
+-----------------------
+
+The builder (Sphinx or rst2man) used for compilation is chosen based
+on variables set in ``Makefile.config`` by the ``configure`` script.
+If ``HAVE_SPHINX`` is 1, ``SPHINXBUILD`` (``sphinx-build`` by default)
+is used to build the documentation.  If ``HAVE_SPHINX`` is not 1, and
+``HAVE_RST2MAN`` is 1, ``RST2MAN`` is used to build the documentation.
+The ``configure`` script autodetects ``rst2man`` or ``rst2man.py`` in
+your ``PATH`` and sets an appropriate ``RST2MAN`` in
+``Makefile.config``.  If neither ``HAVE_SPHINX`` nor ``HAVE_RST2MAN``
+is 1, attempting to build the documentation will fail with an error.
+
+.. _Sphinx: http://sphinx-doc.org/
+.. _Docutils: http://docutils.sourceforge.net/
diff --git a/doc/Makefile.local b/doc/Makefile.local
index 5fb526b..49aa6dd 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -13,22 +13,35 @@ mkdocdeps := python $(srcdir)/$(dir)/mkdocdeps.py
 # Internal variables.
 ALLSPHINXOPTS   := -d $(DOCBUILDDIR)/doctrees $(SPHINXOPTS) $(srcdir)/$(dir)
 
-.PHONY: sphinx-html sphinx-texinfo sphinx-info
+.PHONY: build-html build-info build-texinfo build-man
 
-.PHONY: install-man build-man
+.PHONY: install-info install-man
 
 %.gz: %
 	rm -f $@ && gzip --stdout $^ > $@
 
-sphinx-html:
+build-html:
+ifeq ($(HAVE_SPHINX),1)
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DOCBUILDDIR)/html
+else
+	@echo "fatal: no Sphinx, cannot build HTML docs"
+	@false
+endif
 
-sphinx-texinfo:
+build-texinfo:
+ifeq ($(HAVE_SPHINX),1)
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(DOCBUILDDIR)/texinfo
+else
+	@echo "fatal: no Sphinx or rst2texinfo, cannot build texinfo docs"
+	@false
+endif
 
-sphinx-info: sphinx-texinfo
+build-info: build-texinfo
 	make -C $(DOCBUILDDIR)/texinfo info
 
+install-info: build-info
+	make -C $(DOCBUILDDIR)/texinfo install-info
+
 -include $(dir)/docdeps.mk
 
 MAN_GZIP_FILES := $(addsuffix .gz,${MAN_ROFF_FILES})
@@ -51,20 +64,14 @@ ifeq ($(HAVE_SPHINX),1)
 else ifeq ($(HAVE_RST2MAN),1)
 	$(prerst2x) "$(RST2MAN)" $(srcdir)/doc $(DOCBUILDDIR)/man
 else
-	@echo "Fatal: build dependency fail."
+	@echo "fatal: no Sphinx or rst2man, cannot build man pages"
 	@false
 endif
-	touch ${MAN_ROFF_FILES} $@
-
-# Do not try to build or install man pages if a man page converter is
-# not available.
-ifeq ($(HAVE_SPHINX)$(HAVE_RST2MAN),00)
-build-man:
-install-man:
-	@echo "No sphinx or rst2man, will not install man pages."
-else
-build-man: ${MAN_GZIP_FILES}
-install-man: ${MAN_GZIP_FILES}
+	touch "$@"
+
+build-man: $(MAN_ROFF_FILES)
+
+install-man: $(MAN_GZIP_FILES)
 	mkdir -p "$(DESTDIR)$(mandir)/man1"
 	mkdir -p "$(DESTDIR)$(mandir)/man5"
 	mkdir -p "$(DESTDIR)$(mandir)/man7"
@@ -72,7 +79,6 @@ install-man: ${MAN_GZIP_FILES}
 	install -m0644 $(DOCBUILDDIR)/man/man5/*.5.gz $(DESTDIR)/$(mandir)/man5
 	install -m0644 $(DOCBUILDDIR)/man/man7/*.7.gz $(DESTDIR)/$(mandir)/man7
 	cd $(DESTDIR)/$(mandir)/man1 && ln -sf notmuch.1.gz notmuch-setup.1.gz
-endif
 
 $(dir)/docdeps.mk: $(dir)/conf.py $(dir)/mkdocdeps.py
 	$(mkdocdeps) $(srcdir)/doc $(DOCBUILDDIR) $@
-- 
1.9.1.353.gc66d89d