[PATCH v2 0/5] rst2man.py support and doc-build cleanups

[PATCH v2 0/5] rst2man.py support and doc-build cleanups

[W. Trevor King]

The first four patches from v1 have already landed in master.
This series is v2 of the remainder of the series [1].

In patch 1/5 (v1's 5/7):

* Explicitly empty RST2MAN [2,3], rather than letting external
  environment variables fall through (or explicitly using them to
  bypass configure's detection code [4]).
* Restore HAVE_RST2MAN instead of using non-empty RST2MAN [5].  I'm
  willing to go along with this (hence the patch), but I'd prefer
  dropping the HAVE_* variables.  More details in the commit message
  for patch 5/5.

In patch 4/5 (v1's 7/7):

* Add a '.. -*- rst -*-' prefix to doc/INSTALL [6].
* Fix 'build build' -> 'build' [7].
* Fix 'Building the man Docutils' -> 'Building with Docutils' [7].
* Standardize on build-{html|info|man} and install-{info|man} [8].
* Add notes about the Sphinx/Docutils variables [7].

Patches 3/5 and 5/5 are new since v1, and add Sphinx-less support for
build-html.

[1]: id:cover.1396718720.git.wking@tremily.us
     http://article.gmane.org/gmane.mail.notmuch.general/17732
[2]: id:m2a9bzd2bo.fsf@guru.guru-group.fi
     http://article.gmane.org/gmane.mail.notmuch.general/17742
[3]: id:m21txac0qy.fsf@guru.guru-group.fi
     http://article.gmane.org/gmane.mail.notmuch.general/17775
[4]: id:20140405191917.GF5316@odin.tremily.us
     http://article.gmane.org/gmane.mail.notmuch.general/17745
[5]: id:m24n26c1m9.fsf@guru.guru-group.fi
     http://article.gmane.org/gmane.mail.notmuch.general/17774
[6]: id:87wqejtxs9.fsf@maritornes.cs.unb.ca
     http://article.gmane.org/gmane.mail.notmuch.general/17956
[7]: id:874n271plm.fsf@maritornes.cs.unb.ca
     http://article.gmane.org/gmane.mail.notmuch.general/17746
[8]: id:871txb1j8z.fsf@maritornes.cs.unb.ca
     http://article.gmane.org/gmane.mail.notmuch.general/17754

W. Trevor King (5):
  doc: Allow rst2man.py as an alternative to rst2man
  doc/prerst2man.py: Convert execfile to import
  doc/prerst2x.py: Adjust to handle any output format, not just man
    pages
  doc: Consolidate Makefile targets around {build|install}-{format}
  doc: Add rst2html support for building HTML docs

 Makefile.local     | 14 ++++++++--
 configure          | 41 ++++++++++++++++++++++++++---
 doc/INSTALL        | 47 ++++++++++++++++++++++++----------
 doc/Makefile.local | 48 +++++++++++++++++++---------------
 doc/prerst2man.py  | 63 ---------------------------------------------
 doc/prerst2x.py    | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 6 files changed, 186 insertions(+), 102 deletions(-)
 delete mode 100644 doc/prerst2man.py
 create mode 100644 doc/prerst2x.py

-- 
1.9.1.353.gc66d89d

[PATCH v2 1/5] doc: Allow rst2man.py as an alternative to rst2man

[W. Trevor King]

Gentoo's dev-python/docutils-0.10 installs Docutils scripts with a
*.py extension, so I have /usr/bin/rst2man.py and no rst2man script.
This patch supports users with both types of systems by checking for
rst2man, falling back on rst2man.py, and giving up only if neither is
found.  Users can also set the new RST2MAN path variable explicitly
when they call Make:

  make RST2MAN=/my/custom/rst_to_man_converter build-man

I use POSIX's 'command -v' [1] to find the path to rst2man or
rst2man.py, and save that as RST2MAN in Makefile.config.  Then pass
the configured RST2MAN path through to prerst2man.py to use in its
system call.

We can use a non-empty RST2MAN to check for the availability of an
rst2man program, so there's no need for a separate HAVE_RST2MAN.
However, we keep the existing HAVE_RST2MAN for consistency with
HAVE_SPHINX.

[1]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/command.html
---
 configure          | 15 +++++++++++++--
 doc/Makefile.local |  2 +-
 doc/prerst2man.py  |  9 +++++----
 3 files changed, 19 insertions(+), 7 deletions(-)

diff --git a/configure b/configure
index 9bde2eb..f017af8 100755
--- a/configure
+++ b/configure
@@ -413,17 +413,24 @@ if hash sphinx-build > /dev/null 2>&1 && python -m sphinx.writers.manpage > /dev
     printf "Yes.\n"
     have_sphinx=1
     have_rst2man=0
+    RST2MAN=
 else
     printf "No (falling back to rst2man).\n"
     have_sphinx=0
 
     printf "Checking if rst2man is available... "
     if rst2man -V > /dev/null 2>&1; then
-       printf "Yes.\n"
        have_rst2man=1
+       RST2MAN=$(command -v rst2man)
+       printf "Yes (${RST2MAN}).\n"
+    elif rst2man.py -V > /dev/null 2>&1; then
+       have_rst2man=1
+       RST2MAN=$(command -v rst2man.py)
+       printf "Yes (${RST2MAN}).\n"
     else
-       printf "No (so will not install man pages).\n"
        have_rst2man=0
+       RST2MAN=
+       printf "No (so will not install man pages).\n"
     fi
 fi
 
@@ -820,6 +827,10 @@ HAVE_SPHINX=${have_sphinx}
 # Whether there's a rst2man binary available for building documentation
 HAVE_RST2MAN=${have_rst2man}
 
+# The path to the rst2man program for building documentation.  Set to
+# an empty string if no such program is available.
+RST2MAN=${RST2MAN}
+
 # The directory to which desktop files should be installed
 desktop_dir = \$(prefix)/share/applications
 
diff --git a/doc/Makefile.local b/doc/Makefile.local
index bbd4610..d96cdd5 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -49,7 +49,7 @@ ifeq ($(HAVE_SPHINX),1)
 	    mv $(DOCBUILDDIR)/man/*.$${section} $(DOCBUILDDIR)/man/man$${section}; \
 	done
 else ifeq ($(HAVE_RST2MAN),1)
-	$(prerst2man) $(srcdir)/doc $(DOCBUILDDIR)/man
+	$(prerst2man) "$(RST2MAN)" $(srcdir)/doc $(DOCBUILDDIR)/man
 else
 	@echo "Fatal: build dependency fail."
 	@false
diff --git a/doc/prerst2man.py b/doc/prerst2man.py
index 437dea9..81ce817 100644
--- a/doc/prerst2man.py
+++ b/doc/prerst2man.py
@@ -4,8 +4,9 @@ from os.path import dirname, isdir
 from os import makedirs, system
 import re
 
-sourcedir = argv[1]
-outdir = argv[2]
+rst2man = argv[1]
+sourcedir = argv[2]
+outdir = argv[3]
 
 if not isdir(outdir):
     makedirs(outdir, 0o755)
@@ -59,5 +60,5 @@ for page in man_pages:
     outfile.write("".join(lines))
     outfile.close()
 
-    system('set -x; rst2man {0} {1}/{2}.{3}'
-           .format(filename, outdir, page[0], page[4]))
+    system('set -x; {0} {1} {2}/{3}.{4}'
+           .format(rst2man, filename, outdir, page[0], page[4]))
-- 
1.9.1.353.gc66d89d

[PATCH v2 2/5] doc/prerst2man.py: Convert execfile to import

[W. Trevor King]

excefile is gone in Python 3 [1].  Instead of exec-ing the
configuration, it's easier to insert the source directory in Python's
path [2], and just import the configuration.  With this change,
prerst2man.py is compatible with both Python 2 and 3.

[1]: https://docs.python.org/3.0/whatsnew/3.0.html#builtins
[2]: https://docs.python.org/3/library/sys.html#sys.path
---
 doc/prerst2man.py | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/doc/prerst2man.py b/doc/prerst2man.py
index 81ce817..7d78e9b 100644
--- a/doc/prerst2man.py
+++ b/doc/prerst2man.py
@@ -1,18 +1,20 @@
-from sys import argv
+import sys
 from datetime import date
 from os.path import dirname, isdir
 from os import makedirs, system
 import re
 
-rst2man = argv[1]
-sourcedir = argv[2]
-outdir = argv[3]
+rst2man = sys.argv[1]
+sourcedir = sys.argv[2]
+outdir = sys.argv[3]
+
+sys.path.insert(0, sourcedir)
+import conf
+
 
 if not isdir(outdir):
     makedirs(outdir, 0o755)
 
-execfile(sourcedir + "/conf.py")
-
 
 def header(file, startdocname, command, description, authors, section):
     file.write("""
@@ -29,10 +31,10 @@ def header(file, startdocname, command, description, authors, section):
 '-' * len(description),
 description,
 '-' * len(description),
-date.today().isoformat(), release, section, project))
+date.today().isoformat(), conf.release, section, conf.project))
 
 blankre = re.compile("^\s*$")
-for page in man_pages:
+for page in conf.man_pages:
     outdirname = outdir + '/' + dirname(page[0])
     if not isdir(outdirname):
         makedirs(outdirname, 0o755)
-- 
1.9.1.353.gc66d89d

[PATCH v2 3/5] doc/prerst2x.py: Adjust to handle any output format, not just man pages

[W. Trevor King]

For example, with these changes we can build HTML output using:

  $ prerst2x.py rst2html ${SRCDIR} ${OUTDIR} html

The extension adjustment ensures that the output filenames from the
above command match what we currently generate with sphinx-html.
---
 doc/Makefile.local |  4 +--
 doc/prerst2man.py  | 66 -----------------------------------------------
 doc/prerst2x.py    | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 77 insertions(+), 68 deletions(-)
 delete mode 100644 doc/prerst2man.py
 create mode 100644 doc/prerst2x.py

diff --git a/doc/Makefile.local b/doc/Makefile.local
index d96cdd5..5fb526b 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -7,7 +7,7 @@ SPHINXOPTS    := -q
 SPHINXBUILD   = sphinx-build
 DOCBUILDDIR      := $(dir)/_build
 
-prerst2man := python $(srcdir)/$(dir)/prerst2man.py
+prerst2x := python $(srcdir)/$(dir)/prerst2x.py
 mkdocdeps := python $(srcdir)/$(dir)/mkdocdeps.py
 
 # Internal variables.
@@ -49,7 +49,7 @@ ifeq ($(HAVE_SPHINX),1)
 	    mv $(DOCBUILDDIR)/man/*.$${section} $(DOCBUILDDIR)/man/man$${section}; \
 	done
 else ifeq ($(HAVE_RST2MAN),1)
-	$(prerst2man) "$(RST2MAN)" $(srcdir)/doc $(DOCBUILDDIR)/man
+	$(prerst2x) "$(RST2MAN)" $(srcdir)/doc $(DOCBUILDDIR)/man
 else
 	@echo "Fatal: build dependency fail."
 	@false
diff --git a/doc/prerst2man.py b/doc/prerst2man.py
deleted file mode 100644
index 7d78e9b..0000000
--- a/doc/prerst2man.py
+++ /dev/null
@@ -1,66 +0,0 @@
-import sys
-from datetime import date
-from os.path import dirname, isdir
-from os import makedirs, system
-import re
-
-rst2man = sys.argv[1]
-sourcedir = sys.argv[2]
-outdir = sys.argv[3]
-
-sys.path.insert(0, sourcedir)
-import conf
-
-
-if not isdir(outdir):
-    makedirs(outdir, 0o755)
-
-
-def header(file, startdocname, command, description, authors, section):
-    file.write("""
-{0:s}
-{1:s}
-{2:s}
-
-:Date:   {3:s}
-:Version: {4:s}
-:Manual section: {5:d}
-:Manual group: {6:s}
-
-""".format(
-'-' * len(description),
-description,
-'-' * len(description),
-date.today().isoformat(), conf.release, section, conf.project))
-
-blankre = re.compile("^\s*$")
-for page in conf.man_pages:
-    outdirname = outdir + '/' + dirname(page[0])
-    if not isdir(outdirname):
-        makedirs(outdirname, 0o755)
-    filename = outdir + '/' + page[0] + '.rst'
-    outfile = open(filename, 'w')
-    infile = open(sourcedir + '/' + page[0] + '.rst', 'r')
-
-    # this is a crude hack. We look for the first blank line, and
-    # insert the rst2man header there.
-    #
-    # XXX consider really parsing input
-
-    count = 0
-    lines = infile.readlines()
-    for line in lines:
-        outfile.write(line)
-        if (blankre.match(line)):
-            break
-        count = count + 1
-
-    del lines[0:count + 1]
-
-    header(outfile, *page)
-
-    outfile.write("".join(lines))
-    outfile.close()
-
-    system('set -x; {0} {1} {2}/{3}.{4}'
-           .format(rst2man, filename, outdir, page[0], page[4]))
diff --git a/doc/prerst2x.py b/doc/prerst2x.py
new file mode 100644
index 0000000..4f9213f
--- /dev/null
+++ b/doc/prerst2x.py
@@ -0,0 +1,75 @@
+import sys
+from datetime import date
+from os.path import dirname, isdir
+from os import makedirs, system
+import re
+
+rst2x = sys.argv[1]
+sourcedir = sys.argv[2]
+outdir = sys.argv[3]
+try:
+    extension = sys.argv[4]
+except IndexError:
+    extension = ''
+
+sys.path.insert(0, sourcedir)
+import conf
+
+
+if not isdir(outdir):
+    makedirs(outdir, 0o755)
+
+
+def header(file, startdocname, command, description, authors, section):
+    file.write("""
+{0:s}
+{1:s}
+{2:s}
+
+:Date:   {3:s}
+:Version: {4:s}
+:Manual section: {5:d}
+:Manual group: {6:s}
+
+""".format(
+'-' * len(description),
+description,
+'-' * len(description),
+date.today().isoformat(), conf.release, section, conf.project))
+
+blankre = re.compile("^\s*$")
+for page in conf.man_pages:
+    outdirname = outdir + '/' + dirname(page[0])
+    if not isdir(outdirname):
+        makedirs(outdirname, 0o755)
+    filename = outdir + '/' + page[0] + '.rst'
+    outfile = open(filename, 'w')
+    infile = open(sourcedir + '/' + page[0] + '.rst', 'r')
+
+    # this is a crude hack. We look for the first blank line, and
+    # insert the rst2x header there.
+    #
+    # XXX consider really parsing input
+
+    count = 0
+    lines = infile.readlines()
+    for line in lines:
+        outfile.write(line)
+        if (blankre.match(line)):
+            break
+        count = count + 1
+
+    del lines[0:count + 1]
+
+    header(outfile, *page)
+
+    outfile.write("".join(lines))
+    outfile.close()
+
+    if extension:
+        ext = extension
+    else:
+        ext = page[4]  # man page section
+
+    system('set -x; {0} {1} {2}/{3}.{4}'
+           .format(rst2x, filename, outdir, page[0], ext))
-- 
1.9.1.353.gc66d89d

[PATCH v2 4/5] doc: Consolidate Makefile targets around {build|install}-{format}

[W. Trevor King]

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

[PATCH v2 5/5] doc: Add rst2html support for building HTML docs

[W. Trevor King]

We already fall back to rst2man if Sphinx isn't available for building
the man pages.  With this commit we'll fall back to rst2html for
building the HTML docs too.  The only tricky bit here is that
HAVE_SPHINX explicitly checks for sphinx.writers.manpage.  I'm just
assuming sphinx.writers.html exists, to avoid adding a separate
SPHINX_HTML variable.  However, the HTML builder is Sphinx's default,
so it's hard to imagine it not being installed :p.  Perhaps it would
be better to drop the HAVE_* settings and SPHINXBUILD to use:

* SPHINX2MAN empty for not-available, otherwise path to script that
  can handle '-b manpage'
* SPHINX2HTML empty for not-available, otherwise path to script that
  can handle '-b html'
* RST2MAN empty for not-available, otherwise path to script
* RST2HTML empty for not-available, otherwise path to script

I'm sticking with the less intrusive change for now, but I'm happy
with either approach.
---
 configure          | 26 +++++++++++++++++++++++++-
 doc/INSTALL        |  7 +++++--
 doc/Makefile.local |  2 ++
 3 files changed, 32 insertions(+), 3 deletions(-)

diff --git a/configure b/configure
index f017af8..8fb3d19 100755
--- a/configure
+++ b/configure
@@ -414,8 +414,10 @@ if hash sphinx-build > /dev/null 2>&1 && python -m sphinx.writers.manpage > /dev
     have_sphinx=1
     have_rst2man=0
     RST2MAN=
+    have_rst2html=0
+    RST2HTML=
 else
-    printf "No (falling back to rst2man).\n"
+    printf "No (falling back to Docutils).\n"
     have_sphinx=0
 
     printf "Checking if rst2man is available... "
@@ -432,6 +434,21 @@ else
        RST2MAN=
        printf "No (so will not install man pages).\n"
     fi
+
+    printf "Checking if rst2html is available... "
+    if rst2html -V > /dev/null 2>&1; then
+       have_rst2html=1
+       RST2HTML=$(command -v rst2html)
+       printf "Yes (${RST2HTML}).\n"
+    elif rst2man.py -V > /dev/null 2>&1; then
+       have_rst2html=1
+       RST2HTML=$(command -v rst2html.py)
+       printf "Yes (${RST2HTML}).\n"
+    else
+       have_rst2html=0
+       RST2HTML=
+       printf "No (so can not build HTML docs).\n"
+    fi
 fi
 
 libdir_in_ldconfig=0
@@ -831,6 +848,13 @@ HAVE_RST2MAN=${have_rst2man}
 # an empty string if no such program is available.
 RST2MAN=${RST2MAN}
 
+# Whether there's a rst2html binary available for building documentation
+HAVE_RST2HTML=${have_rst2html}
+
+# The path to the rst2html program for building documentation.  Set to
+# an empty string if no such program is available.
+RST2HTML=${RST2HTML}
+
 # The directory to which desktop files should be installed
 desktop_dir = \$(prefix)/share/applications
 
diff --git a/doc/INSTALL b/doc/INSTALL
index 8352f7b..bd00dcf 100644
--- a/doc/INSTALL
+++ b/doc/INSTALL
@@ -20,8 +20,8 @@ Building with Docutils
 
 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.
+(rst2man, rst2html, etc.) are used instead of Sphinx.  Only the HTML
+and man targets are currently supported.
 
 Configuring the builder
 -----------------------
@@ -36,5 +36,8 @@ 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.
 
+A parallel set of variables (``HAVE_RST2HTML`` and ``RST2HTML``) is
+used when building HTML docs with Docutills.
+
 .. _Sphinx: http://sphinx-doc.org/
 .. _Docutils: http://docutils.sourceforge.net/
diff --git a/doc/Makefile.local b/doc/Makefile.local
index 49aa6dd..d78844a 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -23,6 +23,8 @@ ALLSPHINXOPTS   := -d $(DOCBUILDDIR)/doctrees $(SPHINXOPTS) $(srcdir)/$(dir)
 build-html:
 ifeq ($(HAVE_SPHINX),1)
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DOCBUILDDIR)/html
+else ifeq ($(HAVE_RST2HTML),1)
+	$(prerst2x) "$(RST2HTML)" $(srcdir)/doc $(DOCBUILDDIR)/html html
 else
 	@echo "fatal: no Sphinx, cannot build HTML docs"
 	@false
-- 
1.9.1.353.gc66d89d

Re: [PATCH v2 1/5] doc: Allow rst2man.py as an alternative to rst2man

[Tomi Ollila]

On Sat, May 10 2014, "W. Trevor King" <wking@tremily.us> wrote:

> Gentoo's dev-python/docutils-0.10 installs Docutils scripts with a
> *.py extension, so I have /usr/bin/rst2man.py and no rst2man script.
> This patch supports users with both types of systems by checking for
> rst2man, falling back on rst2man.py, and giving up only if neither is
> found.  Users can also set the new RST2MAN path variable explicitly
> when they call Make:
>
>   make RST2MAN=/my/custom/rst_to_man_converter build-man
>
> I use POSIX's 'command -v' [1] to find the path to rst2man or
> rst2man.py, and save that as RST2MAN in Makefile.config.  Then pass
> the configured RST2MAN path through to prerst2man.py to use in its
> system call.

The comment block above can be removed if the change I suggest below will
be done...

>
> We can use a non-empty RST2MAN to check for the availability of an
> rst2man program, so there's no need for a separate HAVE_RST2MAN.
> However, we keep the existing HAVE_RST2MAN for consistency with
> HAVE_SPHINX.
>
> [1]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/command.html

ditto

> ---
>  configure          | 15 +++++++++++++--
>  doc/Makefile.local |  2 +-
>  doc/prerst2man.py  |  9 +++++----
>  3 files changed, 19 insertions(+), 7 deletions(-)
>
> diff --git a/configure b/configure
> index 9bde2eb..f017af8 100755
> --- a/configure
> +++ b/configure
> @@ -413,17 +413,24 @@ if hash sphinx-build > /dev/null 2>&1 && python -m sphinx.writers.manpage > /dev
>      printf "Yes.\n"
>      have_sphinx=1
>      have_rst2man=0
> +    RST2MAN=
>  else
>      printf "No (falling back to rst2man).\n"
>      have_sphinx=0
>  
>      printf "Checking if rst2man is available... "
>      if rst2man -V > /dev/null 2>&1; then
> -       printf "Yes.\n"
>         have_rst2man=1
> +       RST2MAN=$(command -v rst2man)

This could be just RST2MAN=rst2man -- for consistency -- otherwise we'd
need to give the same treatment to all other commands we check...


> +       printf "Yes (${RST2MAN}).\n"
> +    elif rst2man.py -V > /dev/null 2>&1; then
> +       have_rst2man=1
> +       RST2MAN=$(command -v rst2man.py)

Ditto, RST2MAN=rst2man.py


> +       printf "Yes (${RST2MAN}).\n"
>      else
> -       printf "No (so will not install man pages).\n"
>         have_rst2man=0
> +       RST2MAN=
> +       printf "No (so will not install man pages).\n"
>      fi
>  fi

Tomi

Re: [PATCH v2 3/5] doc/prerst2x.py: Adjust to handle any output format, not just man pages

[Tomi Ollila]

On Sat, May 10 2014, "W. Trevor King" <wking@tremily.us> wrote:

> For example, with these changes we can build HTML output using:
>
>   $ prerst2x.py rst2html ${SRCDIR} ${OUTDIR} html
>
> The extension adjustment ensures that the output filenames from the
> above command match what we currently generate with sphinx-html.

Looks like a good idea...

... how about modeling this name & interface along texi2any(1) 
(or something similar -- I come across this when trying to find
pbmplus/netpbm commands)

otherwise series looks good

Tomi