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
