From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: 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