From b6eaab25b1f63a4012c2101d5d3bda040d6d4266 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sun, 13 Jul 2014 20:10:37 +1700 Subject: [PATCH] [PATCH v3 5/5] doc: Add rst2html support for building HTML docs --- 53/788baa7b9e4d59f0e61959778ca39a91b8aa7b | 185 ++++++++++++++++++++++ 1 file changed, 185 insertions(+) create mode 100644 53/788baa7b9e4d59f0e61959778ca39a91b8aa7b diff --git a/53/788baa7b9e4d59f0e61959778ca39a91b8aa7b b/53/788baa7b9e4d59f0e61959778ca39a91b8aa7b new file mode 100644 index 000000000..f8653afee --- /dev/null +++ b/53/788baa7b9e4d59f0e61959778ca39a91b8aa7b @@ -0,0 +1,185 @@ +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 19B27431FDE + for ; Sat, 12 Jul 2014 20:11:51 -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 G367pZd3dUa0 for ; + Sat, 12 Jul 2014 20:11:43 -0700 (PDT) +Received: from qmta07.emeryville.ca.mail.comcast.net + (qmta07.emeryville.ca.mail.comcast.net [76.96.30.64]) + by olra.theworths.org (Postfix) with ESMTP id CFC55431FC2 + for ; Sat, 12 Jul 2014 20:11:29 -0700 (PDT) +Received: from omta07.emeryville.ca.mail.comcast.net ([76.96.30.59]) + by qmta07.emeryville.ca.mail.comcast.net with comcast + id Rf1Z1o0011GXsucA7fBV76; Sun, 13 Jul 2014 03:11:29 +0000 +Received: from odin.tremily.us ([24.18.63.50]) + by omta07.emeryville.ca.mail.comcast.net with comcast + id RfBU1o00K152l3L8UfBUzj; Sun, 13 Jul 2014 03:11:29 +0000 +Received: from mjolnir.tremily.us (unknown [192.168.0.150]) + by odin.tremily.us (Postfix) with ESMTPS id 4EC051286F09; + Sat, 12 Jul 2014 20:11:28 -0700 (PDT) +Received: (nullmailer pid 31456 invoked by uid 1000); + Sun, 13 Jul 2014 03:10:44 -0000 +From: "W. Trevor King" +To: notmuch@notmuchmail.org +Subject: [PATCH v3 5/5] doc: Add rst2html support for building HTML docs +Date: Sat, 12 Jul 2014 20:10:37 -0700 +Message-Id: + <1a5837370d77c3d24b94b6fbc087c26084e59d3d.1405220724.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=1405221089; + bh=VYTc0KoXqboExTgAKfTOKJlXAH54eABoUJ6B336o5jU=; + h=Received:Received:Received:Received:From:To:Subject:Date: + Message-Id; + b=n/l47x1cUgm2KFrVTWPLdEjn2GPUwQnfJbjkW9Smi0UqO0+EocaTaHGrbN8ga1F/W + d5A1zTn38DXYO/Tv0X5w5d9hx4aeau0yYhy8xtWAcaoGvYqbM2nwIIiweqyO6iEOAC + ddJI0gpcMV1LpuZbovOu8JP5kmGRjvf7hLD1RHMfYFExl4nQIzXMLyCPrY01N63825 + 5cCO40EHpadvC+8DVybEY+CtM0DIrGp0gjJ1wuWeO9Nzi0zJ3ci2mZTitGSIDxzqVB + IrbIGeAl0sP8ncJeDjBVWI80/UZ0TEnYip3dGNuMOXe4blsVFnybRKxKeHIKv/PSds + hO72vmvfMzOlg== +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: Sun, 13 Jul 2014 03:11:51 -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 | 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 + -- 2.26.2