From: W. Trevor King <wking@tremily.us>
Date: Sat, 10 May 2014 16:40:55 +0000 (-0700)
Subject: doc: Add rst2html support for building HTML docs
X-Git-Url: http://git.tremily.us/?p=notmuch.git;a=commitdiff_plain;h=5f852b5f1b0f84bb513d209b9ac1b731f2ec7fa8

doc: Add rst2html support for building HTML docs

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.
---

diff --git a/configure b/configure
index f017af8a..8fb3d198 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 8352f7bc..bd00dcf0 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 49aa6dda..d78844a8 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