From: "W. Trevor King" <wking@tremily.us>
To: notmuch@notmuchmail.org
Subject: [PATCH v2 5/5] doc: Add rst2html support for building HTML docs
Date: Sat, 10 May 2014 10:03:36 -0700
Message-Id:
 <5f852b5f1b0f84bb513d209b9ac1b731f2ec7fa8.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

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