From 87535caf879090b7c22a621d3e329f178f9d87f6 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sun, 13 Jul 2014 20:10:36 +1700 Subject: [PATCH] [PATCH v3 4/5] doc: Consolidate Makefile targets around {build|install}-{format} --- 7e/77bc6e04478449bc7b7e86cc20859697f2d57e | 288 ++++++++++++++++++++++ 1 file changed, 288 insertions(+) create mode 100644 7e/77bc6e04478449bc7b7e86cc20859697f2d57e diff --git a/7e/77bc6e04478449bc7b7e86cc20859697f2d57e b/7e/77bc6e04478449bc7b7e86cc20859697f2d57e new file mode 100644 index 000000000..68f6fc1ca --- /dev/null +++ b/7e/77bc6e04478449bc7b7e86cc20859697f2d57e @@ -0,0 +1,288 @@ +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 1C251431FC3 + for ; Sat, 12 Jul 2014 20:11:37 -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 loM2W6VKVRn8 for ; + Sat, 12 Jul 2014 20:11:29 -0700 (PDT) +Received: from qmta13.emeryville.ca.mail.comcast.net + (qmta13.emeryville.ca.mail.comcast.net [76.96.27.243]) + by olra.theworths.org (Postfix) with ESMTP id 8BF22431FBD + for ; Sat, 12 Jul 2014 20:11:29 -0700 (PDT) +Received: from omta13.emeryville.ca.mail.comcast.net ([76.96.30.52]) + by qmta13.emeryville.ca.mail.comcast.net with comcast + id Rf7B1o00217UAYkADfBVTx; Sun, 13 Jul 2014 03:11:29 +0000 +Received: from odin.tremily.us ([24.18.63.50]) + by omta13.emeryville.ca.mail.comcast.net with comcast + id RfBU1o001152l3L8ZfBUNL; Sun, 13 Jul 2014 03:11:28 +0000 +Received: from mjolnir.tremily.us (unknown [192.168.0.150]) + by odin.tremily.us (Postfix) with ESMTPS id C6A751286F07; + Sat, 12 Jul 2014 20:11:27 -0700 (PDT) +Received: (nullmailer pid 31454 invoked by uid 1000); + Sun, 13 Jul 2014 03:10:44 -0000 +From: "W. Trevor King" +To: notmuch@notmuchmail.org +Subject: [PATCH v3 4/5] doc: Consolidate Makefile targets around + {build|install}-{format} +Date: Sat, 12 Jul 2014 20:10:36 -0700 +Message-Id: + <8f21be7fd9e04f2b0141d1b6d44b1273c2ec42ce.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=ehsgb++EpTqdn5+NMx3mocWuwLSYPIEFRoXN3D75XOo=; + h=Received:Received:Received:Received:From:To:Subject:Date: + Message-Id; + b=B/OWTb7iU/Vi+TKUfzQ1I3U81QqXey/qMh9pMYMI2scFa/wxDE7SFC0UfZN0TU2mR + M01D5FZcgyhTB+LJ+2aPEqrkP5lkWB8IKlApUdkI9nLOA4+qFuFKhLIqND59U2nq5S + mI/Vzz81baWbKQwaSBhpEdN9/ru2rbCJrwaZl8sKx6oLLHmTw3hUlOotg7e1NI/DxF + 1J+TQ/jst5Wou0E2DBbyBr4yHE0LmwP27GbrNTF3tueAyJDy2Oz1hAzOtEgYhe05qY + x3z/ww+mddxvX+sF03NyUeUhbW/lXZ0vHLYb6ZW0x0rG7a0cLXFpXd+SMjR57FGyMK + Sc/sggBVEQw7A== +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:37 -0000 + +The rst2man target was removed in 9d9a700 (doc: build man pages at +build time; introduce HAVE_SPHINX, HAVE_RST2MAN, 2014-03-13), but a +reference in the install docs slipped through. While I was removing +that reference, I also: + +* Converted doc/INSTALL to reStructuredText, so I can link to Sphinx + and Docutils directly. Not everyone has access to Debian's + python-docutils, so it's better to be genric here. +* Converted from an unordered list to paragraphs, because I think it + flows better. +* Dropped the rst2man no-automatic-install caveat. I don't think this + applies to the current code, although I haven't tried to track down + a commit that adds the automatic-install support. Anyhow, + + $ make HAVE_SPHINX=0 HAVE_RST2MAN=1 RST2MAN=rst2man.py DESTDIR=/tmp/ install-man + + works for me. +* Restructured the Makefile to use build- and install- prefixes + consistently, regardless of Sphinx/rst2x backend. +* Instead of disabling the build-man and install-man targets if + HAVE_SPHINX and HAVE_RST2MAN are both empty, just pull build-man and + install-man out of the default build tree. That way: + + $ make HAVE_SPHINX=0 HAVE_RST2MAN=0 build-man + + will fail like it should, instead of successfully doing nothing. If + packagers *do* want to force building the docs, despite any config + settings, you can override the BUILD_MAN and INSTALL_MAN variables: + + $ make BUILD_MAN=build-man all +--- + Makefile.local | 14 ++++++++++++-- + doc/INSTALL | 44 ++++++++++++++++++++++++++++++-------------- + doc/Makefile.local | 42 ++++++++++++++++++++++++------------------ + 3 files changed, 66 insertions(+), 34 deletions(-) + +diff --git a/Makefile.local b/Makefile.local +index fa07d81..83984fd 100644 +--- a/Makefile.local ++++ b/Makefile.local +@@ -43,6 +43,15 @@ GPG_FILE=$(SHA1_FILE).asc + + PV_FILE=bindings/python/notmuch/version.py + ++# Disable docs if we don't have the builders ++ifeq ($(HAVE_SPHINX)$(HAVE_RST2MAN),00) ++BUILD_MAN = ++INSTALL_MAN = ++else ++BUILD_MAN = build-man ++INSTALL_MAN = install-man ++endif ++ + # Smash together user's values with our extra values + FINAL_CFLAGS = -DNOTMUCH_VERSION=$(VERSION) $(CPPFLAGS) $(CFLAGS) $(WARN_CFLAGS) $(extra_cflags) $(CONFIGURE_CFLAGS) + FINAL_CXXFLAGS = $(CPPFLAGS) $(CXXFLAGS) $(WARN_CXXFLAGS) $(extra_cflags) $(extra_cxxflags) $(CONFIGURE_CXXFLAGS) +@@ -58,7 +67,7 @@ endif + FINAL_LIBNOTMUCH_LDFLAGS = $(LDFLAGS) $(AS_NEEDED_LDFLAGS) $(CONFIGURE_LDFLAGS) + + .PHONY: all +-all: notmuch notmuch-shared build-man ++all: notmuch notmuch-shared $(BUILD_MAN) + ifeq ($(MAKECMDGOALS),) + ifeq ($(shell cat .first-build-message 2>/dev/null),) + @NOTMUCH_FIRST_BUILD=1 $(MAKE) --no-print-directory all +@@ -299,7 +308,8 @@ notmuch-shared: $(notmuch_client_modules) lib/$(LINKER_NAME) + $(call quiet,$(FINAL_NOTMUCH_LINKER) $(CFLAGS)) $(notmuch_client_modules) $(FINAL_NOTMUCH_LDFLAGS) -o $@ + + .PHONY: install +-install: all install-man ++ ++install: all $(INSTALL_MAN) + mkdir -p "$(DESTDIR)$(prefix)/bin/" + install notmuch-shared "$(DESTDIR)$(prefix)/bin/notmuch" + ifeq ($(MAKECMDGOALS), install) +diff --git a/doc/INSTALL b/doc/INSTALL +index e37c2b9..8352f7b 100644 +--- a/doc/INSTALL ++++ b/doc/INSTALL +@@ -1,24 +1,40 @@ ++.. -*- rst -*- ++ + This file contains some more detailed information about building and + installing the documentation. + +-Building with sphinx. +---------------------- ++Building with Sphinx ++-------------------- + +-- You need sphinx at least version 1.0. ++With Sphinx_ version 1.0 or greater, you can build HTML, man, and info ++versions of the documentation with:: + +-- You can build build and install man pages with 'make install-man' ++ make build-{html|info|man} + +-- You can build man, info, html, and pdf versions of the docs +- (currently only the man pages) with ++You can build and install the documentation with:: + +- 'make install-{man|info|html|pdf}' ++ make install-{info|man} + +-Building the man pages ++Building with Docutils + ---------------------- + +-- You can build the man pages with rst2man (from python-docutils) with +- 'make rst2man'. +- +-- Currently there is no support to automagically install the resulting +- nroff files, but it should work to modify the target install-man +- in doc/Makefile.local. ++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. ++ ++Configuring the builder ++----------------------- ++ ++The builder (Sphinx or rst2man) used for compilation is chosen based ++on variables set in ``Makefile.config`` by the ``configure`` script. ++If ``HAVE_SPHINX`` is 1, ``SPHINXBUILD`` (``sphinx-build`` by default) ++is used to build the documentation. If ``HAVE_SPHINX`` is not 1, and ++``HAVE_RST2MAN`` is 1, ``RST2MAN`` is used to build the documentation. ++The ``configure`` script autodetects ``rst2man`` or ``rst2man.py`` in ++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. ++ ++.. _Sphinx: http://sphinx-doc.org/ ++.. _Docutils: http://docutils.sourceforge.net/ +diff --git a/doc/Makefile.local b/doc/Makefile.local +index 045f823..9b99c19 100644 +--- a/doc/Makefile.local ++++ b/doc/Makefile.local +@@ -13,22 +13,35 @@ mkdocdeps := python $(srcdir)/$(dir)/mkdocdeps.py + # Internal variables. + ALLSPHINXOPTS := -d $(DOCBUILDDIR)/doctrees $(SPHINXOPTS) $(srcdir)/$(dir) + +-.PHONY: sphinx-html sphinx-texinfo sphinx-info ++.PHONY: build-html build-info build-texinfo build-man + +-.PHONY: install-man build-man ++.PHONY: install-info install-man + + %.gz: % + rm -f $@ && gzip --stdout $^ > $@ + +-sphinx-html: ++build-html: ++ifeq ($(HAVE_SPHINX),1) + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DOCBUILDDIR)/html ++else ++ @echo "fatal: no Sphinx, cannot build HTML docs" ++ @false ++endif + +-sphinx-texinfo: ++build-texinfo: ++ifeq ($(HAVE_SPHINX),1) + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(DOCBUILDDIR)/texinfo ++else ++ @echo "fatal: no Sphinx or rst2texinfo, cannot build texinfo docs" ++ @false ++endif + +-sphinx-info: sphinx-texinfo ++build-info: build-texinfo + make -C $(DOCBUILDDIR)/texinfo info + ++install-info: build-info ++ make -C $(DOCBUILDDIR)/texinfo install-info ++ + -include $(dir)/docdeps.mk + + MAN_GZIP_FILES := $(addsuffix .gz,${MAN_ROFF_FILES}) +@@ -51,20 +64,14 @@ ifeq ($(HAVE_SPHINX),1) + else ifeq ($(HAVE_RST2MAN),1) + $(rstman2any) --converter "$(RST2MAN)" --input $(srcdir)/doc --output $(DOCBUILDDIR)/man + else +- @echo "Fatal: build dependency fail." ++ @echo "fatal: no Sphinx or rst2man, cannot build man pages" + @false + endif +- touch ${MAN_ROFF_FILES} $@ +- +-# Do not try to build or install man pages if a man page converter is +-# not available. +-ifeq ($(HAVE_SPHINX)$(HAVE_RST2MAN),00) +-build-man: +-install-man: +- @echo "No sphinx or rst2man, will not install man pages." +-else +-build-man: ${MAN_GZIP_FILES} +-install-man: ${MAN_GZIP_FILES} ++ touch "$@" ++ ++build-man: $(MAN_ROFF_FILES) ++ ++install-man: $(MAN_GZIP_FILES) + mkdir -p "$(DESTDIR)$(mandir)/man1" + mkdir -p "$(DESTDIR)$(mandir)/man5" + mkdir -p "$(DESTDIR)$(mandir)/man7" +@@ -72,7 +79,6 @@ install-man: ${MAN_GZIP_FILES} + install -m0644 $(DOCBUILDDIR)/man/man5/*.5.gz $(DESTDIR)/$(mandir)/man5 + install -m0644 $(DOCBUILDDIR)/man/man7/*.7.gz $(DESTDIR)/$(mandir)/man7 + cd $(DESTDIR)/$(mandir)/man1 && ln -sf notmuch.1.gz notmuch-setup.1.gz +-endif + + $(dir)/docdeps.mk: $(dir)/conf.py $(dir)/mkdocdeps.py + $(mkdocdeps) $(srcdir)/doc $(DOCBUILDDIR) $@ +-- +1.9.1.353.gc66d89d + -- 2.26.2