From 07ac05d5ecde7bf9925227f4b0e14223dac30b9d Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sun, 11 May 2014 10:03:36 +1700 Subject: [PATCH] [PATCH v2 5/5] doc: Add rst2html support for building HTML docs --- 8c/5d7745857c269e6a35bbcc31830c089abb8ee2 | 186 ++++++++++++++++++++++ 1 file changed, 186 insertions(+) create mode 100644 8c/5d7745857c269e6a35bbcc31830c089abb8ee2 diff --git a/8c/5d7745857c269e6a35bbcc31830c089abb8ee2 b/8c/5d7745857c269e6a35bbcc31830c089abb8ee2 new file mode 100644 index 000000000..f56635c25 --- /dev/null +++ b/8c/5d7745857c269e6a35bbcc31830c089abb8ee2 @@ -0,0 +1,186 @@ +Return-Path: +X-Original-To: notmuch@notmuchmail.org +Delivered-To: notmuch@notmuchmail.org +Received: from localhost (localhost [127.0.0.1]) + by olra.theworths.org (Postfix) with ESMTP id 5FB37431FBF + for ; Sat, 10 May 2014 10:04:33 -0700 (PDT) +X-Virus-Scanned: Debian amavisd-new at olra.theworths.org +X-Amavis-Alert: BAD HEADER SECTION, Duplicate header field: "References" +X-Spam-Flag: NO +X-Spam-Score: 0 +X-Spam-Level: +X-Spam-Status: No, score=0 tagged_above=-999 required=5 + tests=[DKIM_SIGNED=0.1, DKIM_VALID=-0.1, RCVD_IN_DNSWL_NONE=-0.0001] + autolearn=disabled +Received: from olra.theworths.org ([127.0.0.1]) + by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024) + with ESMTP id ts7ItTnDu0OY for ; + Sat, 10 May 2014 10:04:26 -0700 (PDT) +Received: from qmta04.westchester.pa.mail.comcast.net + (qmta04.westchester.pa.mail.comcast.net [76.96.62.40]) + by olra.theworths.org (Postfix) with ESMTP id 10585431FC2 + for ; Sat, 10 May 2014 10:04:20 -0700 (PDT) +Received: from omta04.westchester.pa.mail.comcast.net ([76.96.62.35]) + by qmta04.westchester.pa.mail.comcast.net with comcast + id 0Gvg1o0030ldTLk54H4K6M; Sat, 10 May 2014 17:04:19 +0000 +Received: from odin.tremily.us ([24.18.63.50]) + by omta04.westchester.pa.mail.comcast.net with comcast + id 0H4J1o00X152l3L01H4KWf; Sat, 10 May 2014 17:04:19 +0000 +Received: from mjolnir.tremily.us (unknown [192.168.0.140]) + by odin.tremily.us (Postfix) with ESMTPS id 3B71F11969AD; + Sat, 10 May 2014 10:04:18 -0700 (PDT) +Received: (nullmailer pid 24537 invoked by uid 1000); + Sat, 10 May 2014 17:03:44 -0000 +From: "W. Trevor King" +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> +X-Mailer: git-send-email 1.9.1.353.gc66d89d +In-Reply-To: +References: +In-Reply-To: +References: +DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=comcast.net; + s=q20140121; t=1399741459; + bh=Gu36dE00/vied5NwRm3GgfkIjh9aF/4shKQ+Kr2TpYs=; + h=Received:Received:Received:Received:From:To:Subject:Date: + Message-Id; + b=wqwgmRNTGck7hnz5fimndg2Bk5uv86SNEtB5QzzniJUr7g9AtCYzJJ5BckDmpOLXr + Yk/wZEySlbQUc9KA1GmVxRlVZf3g8TzmUL5JKEdyPY9AaJhKDxDoiKH4ahRw62t5fN + AY8+gqACiOp4YJoRkDDX4nd+z+zh5qXZDc+pkeHR+xHMxwxELEU1UAVhH4VuIeBDhj + f0BG8+D5LBk8IMJL7sJBgBilCXr32GEI98m8klZqdHqDakEb/Cw1U2fq0+4GXCrsDg + tyKsdqLCouYZZwNSj85/XOfl5PrfbpmJTzZbXDPgbYfo5Fs7ZvtMd8tP4cHRzXFpCL + Obl1rcaw+qi1A== +Cc: Tomi Ollila +X-BeenThere: notmuch@notmuchmail.org +X-Mailman-Version: 2.1.13 +Precedence: list +List-Id: "Use and development of the notmuch mail system." + +List-Unsubscribe: , + +List-Archive: +List-Post: +List-Help: +List-Subscribe: , + +X-List-Received-Date: Sat, 10 May 2014 17:04:33 -0000 + +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 + -- 2.26.2