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 f017af8a29d06c2e0e0a9898e0fe9392e6967dc1..8fb3d198b19d932fea65ed00b69dfc940bcd1e5c 100755 (executable)
--- 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 8352f7bcab6c87f3bf0a14d30e4d271212f45553..bd00dcf0acf48bd20a5090d58d5ab01a4f211e5a 100644 (file)
--- 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 49aa6ddabae55cf0466ff0a0234c9365835ef3b5..d78844a897a7770581d7b4cc85a0a852cae44ded 100644 (file)
--- 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