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

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

[W. Trevor King]

Changes since v2 [1]:

* In patches 1/5 and 5/5, use for loops to check for rst2man[.py] and
  rst2html[.py].
* In patches 1/5 and 5/5, store the command names, not the full paths
  (command -v …) [2].
* In patch 3/5, I've added argparse handling to the newly-renamed
  rst-man2any.py.  Tomi suggested modeling the name and UI on texi2any
  [3], but texi2any is for converting a single file, while
  rst-man2any.py is for converting a whole tree (and it takes an
  arbitrary ReST-to-$x converter to do the real work).  I've basically
  just cleaned things up, but if folks aren't satisfied I'm going to
  need more concrete suggestions ;).

Cheers,
Trevor

[1]: id:cover.1399740604.git.wking@tremily.us
     http://thread.gmane.org/gmane.mail.notmuch.general/18291
[2]: id:m2ion3dn0r.fsf@guru.guru-group.fi
     http://article.gmane.org/gmane.mail.notmuch.general/18652
[3]: id:m2lhrzj8kb.fsf@guru.guru-group.fi
     http://article.gmane.org/gmane.mail.notmuch.general/18653

W. Trevor King (5):
  doc: Allow rst2man.py as an alternative to rst2man
  doc/prerst2man.py: Convert execfile to import
  doc/rst-man2any.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          |  45 ++++++++++++++++++++---
 doc/INSTALL        |  47 +++++++++++++++++-------
 doc/Makefile.local |  48 ++++++++++++++----------
 doc/prerst2man.py  |  63 --------------------------------
 doc/rst-man2any.py | 105 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 6 files changed, 217 insertions(+), 105 deletions(-)
 delete mode 100644 doc/prerst2man.py
 create mode 100755 doc/rst-man2any.py

-- 
1.9.1.353.gc66d89d

[PATCH v3 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

We 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.
---
 configure          | 20 +++++++++++++++-----
 doc/Makefile.local |  2 +-
 doc/prerst2man.py  |  9 +++++----
 3 files changed, 21 insertions(+), 10 deletions(-)

diff --git a/configure b/configure
index 9bde2eb..20a2d5f 100755
--- a/configure
+++ b/configure
@@ -413,17 +413,23 @@ 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
-    else
-       printf "No (so will not install man pages).\n"
+    for RST2MAN in rst2man rst2man.py; do
+	if "${RST2MAN}" -V > /dev/null 2>&1; then
+	    have_rst2man=1
+	    printf "Yes (${RST2MAN}).\n"
+	    break
+	fi
+	RST2MAN=
+    done
+    if [ -z "${RST2MAN}" ]; then
        have_rst2man=0
+       printf "No (so will not install man pages).\n"
     fi
 fi
 
@@ -820,6 +826,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 v3 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 v3 3/5] doc/rst-man2any.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:

  $ rst-man2any.py -c rst2html -i ${SRCDIR} -o ${OUTDIR} -e html

The extension adjustment ensures that the output filenames from the
above command match what we currently generate with sphinx-html.

Adding argparse handling at the top of the script tipped this over
into "complicated enough to refactor" for me, so I've shifted the
single-file-conversion logic into a new convert() function and
streamlined things a bit.
---
 doc/Makefile.local |   4 +-
 doc/prerst2man.py  |  66 ---------------------------------
 doc/rst-man2any.py | 105 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 107 insertions(+), 68 deletions(-)
 delete mode 100644 doc/prerst2man.py
 create mode 100755 doc/rst-man2any.py

diff --git a/doc/Makefile.local b/doc/Makefile.local
index d96cdd5..045f823 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
+rstman2any := python $(srcdir)/$(dir)/rst-man2any.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
+	$(rstman2any) --converter "$(RST2MAN)" --input $(srcdir)/doc --output $(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/rst-man2any.py b/doc/rst-man2any.py
new file mode 100755
index 0000000..52a4f9e
--- /dev/null
+++ b/doc/rst-man2any.py
@@ -0,0 +1,105 @@
+#!/usr/bin/python
+
+import argparse
+import datetime
+import os
+import sys
+
+
+def header(stream, description, authors, section, group, version):
+    "Write a man-page's ReST headers to 'stream'."
+    if len(authors) != 1:
+        raise NotImplementedError(
+            'cannot handle {count} authors ({authors}'.format(
+                count=len(authors), authors=authors))
+    stream.write('\n'.join([
+        '{description_rule}',
+        '{description}',
+        '{description_rule}',
+        '',
+        ':Author: {author}',
+        ':Date: {date}',
+        ':Version: {version}',
+        ':Manual section: {section:d}',
+        ':Manual group: {group}',
+        '',
+        '']).format(
+            description=description,
+            description_rule='-' * len(description),
+            author=authors[0],
+            date=datetime.date.today().isoformat(),
+            version=version,
+            section=section,
+            group=group))
+
+
+def convert(startdocname, description, authors, section,
+            group, version, source_dir, output_dir, command, extension=None):
+    """Convert the ReST source at path to the target format in 'output_dir'.
+
+    The initial arguments (startdocname through section) follow
+    Sphinx's man_pages option [1].
+
+    [1]: http://sphinx-doc.org/config.html#confval-man_pages
+    """
+    source_path = os.path.join(source_dir, startdocname) + '.rst'
+    output_base = os.path.join(output_dir, startdocname)
+    temp_path = output_base + '.rst'
+    if extension:
+        ext = extension
+    else:
+        ext = str(section)
+    output_path = '{base}.{ext}'.format(base=output_base, ext=ext)
+    dirname = os.path.dirname(output_path)
+    if not os.path.isdir(dirname):
+        os.makedirs(dirname, 0o755)
+    with open(source_path, 'r') as source:
+        with open(temp_path, 'w') as temp:
+            # this is a crude hack. We look for the first blank line, and
+            # insert the man-page headers there.
+            #
+            # XXX consider really parsing input
+            need_header = True
+            for line in source:
+                temp.write(line)
+                if need_header and not line.strip():
+                    header(
+                        stream=temp, description=description, authors=authors,
+                        section=section, group=group, version=version)
+                    need_header = False
+    os.system('set -x; {command} {source_path} {output_path}'.format(
+        command=command,
+        source_path=temp_path,
+        output_path=output_path))
+
+
+if __name__ == '__main__':
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description='Convert reStructuredText man pages to other formats.')
+    parser.add_argument(
+        '-i', '--input', default='_build',
+        help='Input directory')
+    parser.add_argument(
+        '-o', '--output', default='.',
+        help='Output directory')
+    parser.add_argument(
+        '-c', '--converter', default='rst2man',
+        help='ReST converter for your target output')
+    parser.add_argument(
+        '-e', '--extension',
+        help='Optional extension for the output files')
+
+    args = parser.parse_args()
+
+    sys.path.insert(0, args.input)
+    import conf
+
+    for startdocname, name, description, authors, section in conf.man_pages:
+        convert(
+            startdocname=startdocname, description=description,
+            authors=authors, section=section, group=conf.project,
+            version=conf.release, source_dir=args.input,
+            output_dir=args.output, command=args.converter,
+            extension=args.extension)
-- 
1.9.1.353.gc66d89d

[PATCH v3 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 045f823..9b99c19 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)
 	$(rstman2any) --converter "$(RST2MAN)" --input $(srcdir)/doc --output $(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 v3 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          | 25 ++++++++++++++++++++++++-
 doc/INSTALL        |  7 +++++--
 doc/Makefile.local |  2 ++
 3 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/configure b/configure
index 20a2d5f..446439f 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... "
@@ -431,6 +433,20 @@ else
        have_rst2man=0
        printf "No (so will not install man pages).\n"
     fi
+
+    printf "Checking if rst2html is available... "
+    for RST2HTML in rst2html rst2html.py; do
+	if "${RST2HTML}" -V > /dev/null 2>&1; then
+	    have_rst2html=1
+	    printf "Yes (${RST2HTML}).\n"
+	    break
+	fi
+	RST2HTML=
+    done
+    if [ -z "${RST2HTML}" ]; then
+       have_rst2html=0
+       printf "No (so can not build HTML docs).\n"
+    fi
 fi
 
 libdir_in_ldconfig=0
@@ -830,6 +846,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 9b99c19..e0a6963 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)
+	$(rstman2any) --converter "$(RST2HTML)" --input $(srcdir)/doc --output $(DOCBUILDDIR)/html --extension html
 else
 	@echo "fatal: no Sphinx, cannot build HTML docs"
 	@false
-- 
1.9.1.353.gc66d89d

Re: [PATCH v3 0/5] rst2man.py support and doc-build cleanups

[Tomi Ollila]

On Sun, Jul 13 2014, "W. Trevor King" <wking@tremily.us> wrote:

> Changes since v2 [1]:
>
> * In patches 1/5 and 5/5, use for loops to check for rst2man[.py] and
>   rst2html[.py].
> * In patches 1/5 and 5/5, store the command names, not the full paths
>   (command -v …) [2].
> * In patch 3/5, I've added argparse handling to the newly-renamed
>   rst-man2any.py.  Tomi suggested modeling the name and UI on texi2any
>   [3], but texi2any is for converting a single file, while
>   rst-man2any.py is for converting a whole tree (and it takes an
>   arbitrary ReST-to-$x converter to do the real work).  I've basically
>   just cleaned things up, but if folks aren't satisfied I'm going to
>   need more concrete suggestions ;).

The series now looks good to me, I don't have time to test it now but will
do it after Jul 20th.

I am satisfied with rst-man2any.py, but as being normal picky me I wonder
whether the command prefix 'rst-' is being too generic i.e. is invading
that "namespace". If no one else has the same feeling (or the feeling is
just wrong (or insignificant)) then this can be forgotten :D

>
> Cheers,
> Trevor

Thanks, good work!


Tomi

>
> [1]: id:cover.1399740604.git.wking@tremily.us
>      http://thread.gmane.org/gmane.mail.notmuch.general/18291
> [2]: id:m2ion3dn0r.fsf@guru.guru-group.fi
>      http://article.gmane.org/gmane.mail.notmuch.general/18652
> [3]: id:m2lhrzj8kb.fsf@guru.guru-group.fi
>      http://article.gmane.org/gmane.mail.notmuch.general/18653
>
> W. Trevor King (5):
>   doc: Allow rst2man.py as an alternative to rst2man
>   doc/prerst2man.py: Convert execfile to import
>   doc/rst-man2any.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          |  45 ++++++++++++++++++++---
>  doc/INSTALL        |  47 +++++++++++++++++-------
>  doc/Makefile.local |  48 ++++++++++++++----------
>  doc/prerst2man.py  |  63 --------------------------------
>  doc/rst-man2any.py | 105 +++++++++++++++++++++++++++++++++++++++++++++++++++++
>  6 files changed, 217 insertions(+), 105 deletions(-)
>  delete mode 100644 doc/prerst2man.py
>  create mode 100755 doc/rst-man2any.py
>
> -- 
> 1.9.1.353.gc66d89d
>
> _______________________________________________
> notmuch mailing list
> notmuch@notmuchmail.org
> http://notmuchmail.org/mailman/listinfo/notmuch

Re: [PATCH v3 0/5] rst2man.py support and doc-build cleanups

[David Bremner]

Tomi Ollila <tomi.ollila@iki.fi> writes:
>
> The series now looks good to me, I don't have time to test it now but will
> do it after Jul 20th.
>
> I am satisfied with rst-man2any.py, but as being normal picky me I wonder
> whether the command prefix 'rst-' is being too generic i.e. is invading
> that "namespace". If no one else has the same feeling (or the feeling is
> just wrong (or insignificant)) then this can be forgotten :D

I would not worry too much about the name of a private command used in
the build process.

d

Re: [PATCH v3 0/5] rst2man.py support and doc-build cleanups

[W. Trevor King]

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

On Sun, Jul 13, 2014 at 09:05:41AM +0300, Tomi Ollila wrote:
> I am satisfied with rst-man2any.py, but as being normal picky me I
> wonder whether the command prefix 'rst-' is being too generic
> i.e. is invading that "namespace". If no one else has the same
> feeling (or the feeling is just wrong (or insignificant)) then this
> can be forgotten :D

For what it's worth, I don't have any ‘rst-*’ commands on my system.
I do have ‘rst2*’ commands, and an ‘rstpep2html.py’.  I'm happy to
rename to whatever, but rst-man2any.py was the best that I could think
of following the texi2any pattern.

Cheers,
Trevor

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: [PATCH v3 0/5] rst2man.py support and doc-build cleanups

[Tomi Ollila]

On Sun, Jul 13 2014, "W. Trevor King" <wking@tremily.us> wrote:

> On Sun, Jul 13, 2014 at 09:05:41AM +0300, Tomi Ollila wrote:
>> I am satisfied with rst-man2any.py, but as being normal picky me I
>> wonder whether the command prefix 'rst-' is being too generic
>> i.e. is invading that "namespace". If no one else has the same
>> feeling (or the feeling is just wrong (or insignificant)) then this
>> can be forgotten :D
>
> For what it's worth, I don't have any ‘rst-*’ commands on my system.
> I do have ‘rst2*’ commands, and an ‘rstpep2html.py’.  I'm happy to
> rename to whatever, but rst-man2any.py was the best that I could think
> of following the texi2any pattern.

Well, IMO both the first 'prerst2x.py' (or how was it called) & this
rst-man2any.py would be good as those were to be included as is to notmuch
-- when there is something else to comment then I often try to suggest
some little details in style (and might not always get it right...)

But now, as this rst-man2any.py uses argparse -- which is not python 2.6
compatible (and we currently kind of try to keep python 2.6 supported 
(rhel 6, and compatibles, among other older but relevant distros(*)))

Therefore I simply suggest to return back to prerst2x.py -- as other
alternatives are just too tedious to do -- unnecessary waste of time.

> Cheers,
> Trevor

(*) although newer-enough zlib is not there -- but again, that one patch of
mine should be easy enough to apply...


Tomi