From aa9980a014ffe5cb926e873be0917c5adfefbcba Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sun, 11 May 2014 10:03:35 +1700 Subject: [PATCH] [PATCH v2 4/5] doc: Consolidate Makefile targets around {build|install}-{format} --- 1a/6709e6608396264209ca64f51cb92df47193b3 | 288 ++++++++++++++++++++++ 1 file changed, 288 insertions(+) create mode 100644 1a/6709e6608396264209ca64f51cb92df47193b3 diff --git a/1a/6709e6608396264209ca64f51cb92df47193b3 b/1a/6709e6608396264209ca64f51cb92df47193b3 new file mode 100644 index 000000000..be8b8c521 --- /dev/null +++ b/1a/6709e6608396264209ca64f51cb92df47193b3 @@ -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 40F41431FDF + for ; Sat, 10 May 2014 10:04:38 -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 YezVV1DonmUH for ; + Sat, 10 May 2014 10:04:32 -0700 (PDT) +Received: from qmta12.westchester.pa.mail.comcast.net + (qmta12.westchester.pa.mail.comcast.net [76.96.59.227]) + by olra.theworths.org (Postfix) with ESMTP id 449BC431FC4 + for ; Sat, 10 May 2014 10:04:21 -0700 (PDT) +Received: from omta07.westchester.pa.mail.comcast.net ([76.96.62.59]) + by qmta12.westchester.pa.mail.comcast.net with comcast + id 0Ghz1o0011GhbT85CH4KKs; Sat, 10 May 2014 17:04:19 +0000 +Received: from odin.tremily.us ([24.18.63.50]) + by omta07.westchester.pa.mail.comcast.net with comcast + id 0H4H1o00L152l3L3TH4Jvl; 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 B1AC511969AB; + Sat, 10 May 2014 10:04:17 -0700 (PDT) +Received: (nullmailer pid 24535 invoked by uid 1000); + Sat, 10 May 2014 17:03:44 -0000 +From: "W. Trevor King" +To: notmuch@notmuchmail.org +Subject: [PATCH v2 4/5] doc: Consolidate Makefile targets around + {build|install}-{format} +Date: Sat, 10 May 2014 10:03:35 -0700 +Message-Id: + <4fb5447805a8d5bb8da74c0196f12ac4ffaf4394.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=oDNX00yjXoSIulFPjlLo2PE9aYbMjg4skc5+Cu+CFXg=; + h=Received:Received:Received:Received:From:To:Subject:Date: + Message-Id; + b=Nul4zX+Mnr1FSJur2Iz3TQiL3JKP9QoQJzWK3jbnh1egc/gAbrmoKr2FIh9QO/7C3 + 55cS2bH9c23QUv4ynhu0qxlJRPc7rDF6s6NdU4TIlbBrE4MRIobEhCOaFX/swD0aQZ + enGnLmDYhVdjgAZpppKwuWe/IoXf8j2iyUXeBO1TQSgjScWb4OQ14XKYFz2AE1EqQr + TqTk74GHi1A9YqF+z6R9Y3FPSbXDKIy9tTXHU95QsKgIpWIWaCX9LvbYIC19ZdjoeY + XVkeQQ2GD07b/c5D9Etz28Qff2L1mb9p5C8jDe4TBo4X6CSQheZ7kT5+iI13/Ojj2G + VHx1Zd1C9C9LA== +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:38 -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 5fb526b..49aa6dd 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) + $(prerst2x) "$(RST2MAN)" $(srcdir)/doc $(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