debian/notmuch
1
0
Fork 0
mirror of https://git.notmuchmail.org/git/notmuch synced 2024-11-25 04:18:08 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
notmuch/doc/Makefile.local

142 lines
4.9 KiB
Text
Raw Normal View History

doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
# -*- makefile -*-
dir := doc
# You can set these variables from the command line.
doc: fix out-of-tree build The subtle part is adding .rst and .py files to vpath so they can be used as dependencies without prefixing with $(srcdir) We also change the interface to mkbuildeps.py: rather than getting the containing directory from the conf file path, we go the other way.
2014-03-20 01:48:03 +01:00
SPHINXOPTS := -q
doc: exclude notmuch-emacs.rst if emacs is not present. This will still generate a warning about an excluded document in the toctree, but it cuts down on the noise quite a lot.
2019-04-22 01:41:34 +02:00
SPHINXBUILD = HAVE_EMACS=${HAVE_EMACS} sphinx-build
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
DOCBUILDDIR := $(dir)/_build
# Internal variables.
doc: use separate doctrees for distinct builders It seems our previous attempt with order-only targets was not sufficient to avoid problems with sphinx-builds doctree cache [0]. Looking around at other people's approaches [1], using separate doctrees was suggested. I guess there might be a slight loss of efficiency, but it seems more robust. [0]: build failures were first noticed in Debian experimental, but I was able to duplicate it in my usual build environment about 1 in 8 builds. [1]: in particular https://salsa.debian.org/mpd-team/mpc/commit/9e3fc1657d043d75755993846c93f7700b97f907
2019-06-01 04:24:52 +02:00
ALLSPHINXOPTS := $(SPHINXOPTS) $(srcdir)/$(dir)
doc: build and install doxygen api docs In order to support out of tree builds and avoid hardcoding version number, generate `doc/config.dox` from configure.
2014-07-01 18:40:33 +02:00
APIMAN := $(DOCBUILDDIR)/man/man3/notmuch.3
DOXYFILE := $(srcdir)/$(dir)/doxygen.cfg
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
build: generate man page list from source files, not conf.py Use $(wildcard ...) to generate the list of man pages based on the rst source files present in the man page directories, instead of reading conf.py. This has three main benefits: 1) This makes the man page build slightly less complicated and easier to understand. At least there are fewer moving parts. 2) This makes the build fail if we add a man page rst file, but fail to add it to conf.py. 3) We can use Sphinx constructs in conf.py that are not available when importing the file into a normal python program such as mkdocdeps.py.
2016-11-05 21:18:17 +01:00
MAN1_RST := $(wildcard $(srcdir)/doc/man1/*.rst)
MAN5_RST := $(wildcard $(srcdir)/doc/man5/*.rst)
MAN7_RST := $(wildcard $(srcdir)/doc/man7/*.rst)
MAN_RST_FILES := $(MAN1_RST) $(MAN5_RST) $(MAN7_RST)
doc: use stamp file to control rebuilding texi Apparently the sphinx-doc texinfo builder is not smart enough to only rebuild those files where the source has changed.
2019-04-21 18:53:03 +02:00
ALL_RST_FILES := $(MAN_RST_FILES) $(srcdir)/doc/notmuch-emacs.rst
build: generate man page list from source files, not conf.py Use $(wildcard ...) to generate the list of man pages based on the rst source files present in the man page directories, instead of reading conf.py. This has three main benefits: 1) This makes the man page build slightly less complicated and easier to understand. At least there are fewer moving parts. 2) This makes the build fail if we add a man page rst file, but fail to add it to conf.py. 3) We can use Sphinx constructs in conf.py that are not available when importing the file into a normal python program such as mkdocdeps.py.
2016-11-05 21:18:17 +01:00
MAN1_ROFF := $(patsubst $(srcdir)/doc/%,$(DOCBUILDDIR)/man/%,$(MAN1_RST:.rst=.1))
MAN5_ROFF := $(patsubst $(srcdir)/doc/%,$(DOCBUILDDIR)/man/%,$(MAN5_RST:.rst=.5))
MAN7_ROFF := $(patsubst $(srcdir)/doc/%,$(DOCBUILDDIR)/man/%,$(MAN7_RST:.rst=.7))
MAN_ROFF_FILES := $(MAN1_ROFF) $(MAN5_ROFF) $(MAN7_ROFF)
MAN_GZIP_FILES := $(addsuffix .gz,${MAN_ROFF_FILES})
doc: install build and install info pages All of the man pages are installed as info pages, plus the (unfinished) notmuch-emacs manual
2018-05-21 22:08:51 +02:00
MAN1_TEXI := $(patsubst $(srcdir)/doc/man1/%.rst,$(DOCBUILDDIR)/texinfo/%.texi,$(MAN1_RST))
MAN5_TEXI := $(patsubst $(srcdir)/doc/man5/%.rst,$(DOCBUILDDIR)/texinfo/%.texi,$(MAN5_RST))
MAN7_TEXI := $(patsubst $(srcdir)/doc/man7/%.rst,$(DOCBUILDDIR)/texinfo/%.texi,$(MAN7_RST))
INFO_TEXI_FILES := $(MAN1_TEXI) $(MAN5_TEXI) $(MAN7_TEXI) $(DOCBUILDDIR)/texinfo/notmuch-emacs.texi
INFO_INFO_FILES := $(INFO_TEXI_FILES:.texi=.info)
doc: build man pages at build time; introduce HAVE_SPHINX, HAVE_RST2MAN This helps avoid build artifacts (namely, nroff and gzipped-nroff man pages) owned by root. The variables allow choosing which generator to use for the man page. These will be hooked to configure in a following commit.
2014-03-13 04:21:14 +01:00
.PHONY: sphinx-html sphinx-texinfo sphinx-info
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
doc: build and install doxygen api docs In order to support out of tree builds and avoid hardcoding version number, generate `doc/config.dox` from configure.
2014-07-01 18:40:33 +02:00
.PHONY: install-man build-man apidocs install-apidocs
doc: install sphinx version of man pages The python script mkdocdeps.py is used to import the list of man pages from the sphinx configuration to make. This will delete the (release only) target update-man-versions. This will be replaced in a followup commit.
2014-03-05 14:34:10 +01:00
%.gz: %
rm -f $@ && gzip --stdout $^ > $@
doc/emacs: require extracted docstrings for sphinx or info manual We need to use the stamp file here in order not to depend on the order the submakefiles are included.
2018-06-14 02:32:40 +02:00
ifeq ($(WITH_EMACS),1)
doc: make man pages depend on emacs docstrings This is nonsensical on the face of it, but is needed (for now) because the notmuch-emacs page is unconditionally included in index.rst.
2018-12-20 09:30:11 +01:00
$(DOCBUILDDIR)/.roff.stamp sphinx-html sphinx-texinfo: docstring.stamp
doc/emacs: require extracted docstrings for sphinx or info manual We need to use the stamp file here in order not to depend on the order the submakefiles are included.
2018-06-14 02:32:40 +02:00
endif
doc: use stamp file for html docs These are less time consuming than the texi docs to rebuild (because the texi rebuild triggers info rebuild), but still take noticable time.
2019-04-21 19:00:18 +02:00
sphinx-html: $(DOCBUILDDIR)/.html.stamp
$(DOCBUILDDIR)/.html.stamp: $(ALL_RST_FILES)
doc: use separate doctrees for distinct builders It seems our previous attempt with order-only targets was not sufficient to avoid problems with sphinx-builds doctree cache [0]. Looking around at other people's approaches [1], using separate doctrees was suggested. I guess there might be a slight loss of efficiency, but it seems more robust. [0]: build failures were first noticed in Debian experimental, but I was able to duplicate it in my usual build environment about 1 in 8 builds. [1]: in particular https://salsa.debian.org/mpd-team/mpc/commit/9e3fc1657d043d75755993846c93f7700b97f907
2019-06-01 04:24:52 +02:00
$(SPHINXBUILD) -b html -d $(DOCBUILDDIR)/html_doctrees $(ALLSPHINXOPTS) $(DOCBUILDDIR)/html
doc: use stamp file for html docs These are less time consuming than the texi docs to rebuild (because the texi rebuild triggers info rebuild), but still take noticable time.
2019-04-21 19:00:18 +02:00
touch $@
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
doc: use stamp file to control rebuilding texi Apparently the sphinx-doc texinfo builder is not smart enough to only rebuild those files where the source has changed.
2019-04-21 18:53:03 +02:00
sphinx-texinfo: $(DOCBUILDDIR)/.texi.stamp
$(DOCBUILDDIR)/.texi.stamp: $(ALL_RST_FILES)
doc: use separate doctrees for distinct builders It seems our previous attempt with order-only targets was not sufficient to avoid problems with sphinx-builds doctree cache [0]. Looking around at other people's approaches [1], using separate doctrees was suggested. I guess there might be a slight loss of efficiency, but it seems more robust. [0]: build failures were first noticed in Debian experimental, but I was able to duplicate it in my usual build environment about 1 in 8 builds. [1]: in particular https://salsa.debian.org/mpd-team/mpc/commit/9e3fc1657d043d75755993846c93f7700b97f907
2019-06-01 04:24:52 +02:00
$(SPHINXBUILD) -b texinfo -d $(DOCBUILDDIR)/texinfo_doctrees $(ALLSPHINXOPTS) $(DOCBUILDDIR)/texinfo
doc: use stamp file to control rebuilding texi Apparently the sphinx-doc texinfo builder is not smart enough to only rebuild those files where the source has changed.
2019-04-21 18:53:03 +02:00
touch $@
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
sphinx-info: sphinx-texinfo
doc/build: use $(MAKE) instead of make This should silence some warnings about the jobserver, but also make it easier to build the docs where GNU make is called something other than make. Based on a patch from aidecoe.
2019-03-20 00:50:28 +01:00
$(MAKE) -C $(DOCBUILDDIR)/texinfo info
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
doc: configure detection of sphinx and rst2man Because sphinx-build does not provide a convenient way of listing which builders exist, and some people actually have pre 1.0 sphinx, we try loading a relevant python module. Currently the assumption is that no python in path -> no sphinx-build in path.
2014-03-13 04:21:16 +01:00
# Use the man page converter that is available. We should never depend
# on MAN_ROFF_FILES if a converter is not available.
doc: Fix parallel build of roff files The roff build rule builds all of the roff files in a single command. Previously, this was expressed as a multi-target rule, but since this is equivalent to specifying a copy of the rule for each target, make -jN could start up to N parallel instances of this command. Fix this by bottlenecking this rule through a single stamp file. This also removes the unused man.stamp from CLEAN.
2014-04-17 22:34:57 +02:00
${MAN_ROFF_FILES}: $(DOCBUILDDIR)/.roff.stamp
# By using $(DOCBUILDDIR)/.roff.stamp instead of ${MAN_ROFF_FILES}, we
# convey to make that a single invocation of this recipe builds all
# of the roff files. This prevents parallel make from starting an
# instance of this recipe for each roff file.
$(DOCBUILDDIR)/.roff.stamp: ${MAN_RST_FILES}
doc: build man pages at build time; introduce HAVE_SPHINX, HAVE_RST2MAN This helps avoid build artifacts (namely, nroff and gzipped-nroff man pages) owned by root. The variables allow choosing which generator to use for the man page. These will be hooked to configure in a following commit.
2014-03-13 04:21:14 +01:00
ifeq ($(HAVE_SPHINX),1)
doc: use separate doctrees for distinct builders It seems our previous attempt with order-only targets was not sufficient to avoid problems with sphinx-builds doctree cache [0]. Looking around at other people's approaches [1], using separate doctrees was suggested. I guess there might be a slight loss of efficiency, but it seems more robust. [0]: build failures were first noticed in Debian experimental, but I was able to duplicate it in my usual build environment about 1 in 8 builds. [1]: in particular https://salsa.debian.org/mpd-team/mpc/commit/9e3fc1657d043d75755993846c93f7700b97f907
2019-06-01 04:24:52 +02:00
$(SPHINXBUILD) -b man -d $(DOCBUILDDIR)/man_doctrees $(ALLSPHINXOPTS) $(DOCBUILDDIR)/man
doc: build man pages into hierarchy, fix help test. It turns out there was a reason the old man pages were stored in a man compatible hierarchy, namely so that we could run man on them before installing. Hardcode doc build location into test suite. This isn't ideal, but let's unbreak the test suite for now.
2014-03-13 04:21:15 +01:00
for section in 1 5 7; do \
mkdir -p $(DOCBUILDDIR)/man/man$${section}; \
mv $(DOCBUILDDIR)/man/*.$${section} $(DOCBUILDDIR)/man/man$${section}; \
done
doc: build man pages at build time; introduce HAVE_SPHINX, HAVE_RST2MAN This helps avoid build artifacts (namely, nroff and gzipped-nroff man pages) owned by root. The variables allow choosing which generator to use for the man page. These will be hooked to configure in a following commit.
2014-03-13 04:21:14 +01:00
else
doc: configure detection of sphinx and rst2man Because sphinx-build does not provide a convenient way of listing which builders exist, and some people actually have pre 1.0 sphinx, we try loading a relevant python module. Currently the assumption is that no python in path -> no sphinx-build in path.
2014-03-13 04:21:16 +01:00
@echo "Fatal: build dependency fail."
@false
doc: build man pages at build time; introduce HAVE_SPHINX, HAVE_RST2MAN This helps avoid build artifacts (namely, nroff and gzipped-nroff man pages) owned by root. The variables allow choosing which generator to use for the man page. These will be hooked to configure in a following commit.
2014-03-13 04:21:14 +01:00
endif
build: do not touch roff files after sphinx-build If Sphinx fails to create any of the roff files, having touch create them hides the errors until someone realizes, possibly much later, that the resulting files are empty. (Note that gzip doesn't fail on empty input files.) Sphinx will change the timestamps of any files it has written anyway.
2016-11-05 21:18:16 +01:00
touch $@
doc: install sphinx version of man pages The python script mkdocdeps.py is used to import the list of man pages from the sphinx configuration to make. This will delete the (release only) target update-man-versions. This will be replaced in a followup commit.
2014-03-05 14:34:10 +01:00
doc: build and install doxygen api docs In order to support out of tree builds and avoid hardcoding version number, generate `doc/config.dox` from configure.
2014-07-01 18:40:33 +02:00
install-man: install-apidocs
ifeq ($(HAVE_DOXYGEN),1)
MAN_GZIP_FILES += ${APIMAN}.gz
apidocs: $(APIMAN)
doc: gzipped notmuch.3 before trying to install notmuch.3.gz If HAVE_SPHINX=0 but HAVE_DOXYGEN=1, then the previous version was trying to install notmuch.3.gz but only got as far as creating notmuch.3
2015-01-25 15:04:51 +01:00
install-apidocs: ${APIMAN}.gz
doc: build and install doxygen api docs In order to support out of tree builds and avoid hardcoding version number, generate `doc/config.dox` from configure.
2014-07-01 18:40:33 +02:00
mkdir -p "$(DESTDIR)$(mandir)/man3"
build: only install known man pages Install man pages based on $(MAN_GZIP_FILES), which directly corresponds to the man page source rst files. This way we can filter the man pages to be installed as needed.
2016-11-05 21:18:18 +01:00
install -m0644 $(filter %.3.gz,$(MAN_GZIP_FILES)) $(DESTDIR)/$(mandir)/man3
doc: build and install doxygen api docs In order to support out of tree builds and avoid hardcoding version number, generate `doc/config.dox` from configure.
2014-07-01 18:40:33 +02:00
$(APIMAN): $(dir)/config.dox $(srcdir)/$(dir)/doxygen.cfg $(srcdir)/lib/notmuch.h
mkdir -p $(DOCBUILDDIR)/man/man3
doxygen $(DOXYFILE)
doc: 'rm -f' potential doxygen temporary output file Some (older) Doxygen versions do not create such a temporary file.
2014-09-01 20:44:59 +02:00
rm -f $(DOCBUILDDIR)/man/man3/_*.3
doc: postprocess notmuch.3 Remove excess italics from doxygen output. It seems to make no sense (and is certainly ugly) to italicize the first argument to the .RI macro.
2014-07-01 21:13:03 +02:00
perl -pi -e 's/^[.]RI "\\fI/.RI "\\fP/' $(APIMAN)
doc: build and install doxygen api docs In order to support out of tree builds and avoid hardcoding version number, generate `doc/config.dox` from configure.
2014-07-01 18:40:33 +02:00
else
apidocs:
install-apidocs:
endif
doc: configure detection of sphinx and rst2man Because sphinx-build does not provide a convenient way of listing which builders exist, and some people actually have pre 1.0 sphinx, we try loading a relevant python module. Currently the assumption is that no python in path -> no sphinx-build in path.
2014-03-13 04:21:16 +01:00
# Do not try to build or install man pages if a man page converter is
# not available.
doc: remove support for rst2man It was becoming increasingly complicated to support rst2man, and there were apparently not many people that relied on it.
2015-01-18 17:55:10 +01:00
ifeq ($(HAVE_SPHINX),0)
doc: configure detection of sphinx and rst2man Because sphinx-build does not provide a convenient way of listing which builders exist, and some people actually have pre 1.0 sphinx, we try loading a relevant python module. Currently the assumption is that no python in path -> no sphinx-build in path.
2014-03-13 04:21:16 +01:00
build-man:
install-man:
doc: remove support for rst2man It was becoming increasingly complicated to support rst2man, and there were apparently not many people that relied on it.
2015-01-18 17:55:10 +01:00
@echo "No sphinx, will not install man pages."
doc: configure detection of sphinx and rst2man Because sphinx-build does not provide a convenient way of listing which builders exist, and some people actually have pre 1.0 sphinx, we try loading a relevant python module. Currently the assumption is that no python in path -> no sphinx-build in path.
2014-03-13 04:21:16 +01:00
else
build-man: ${MAN_GZIP_FILES}
doc: install sphinx version of man pages The python script mkdocdeps.py is used to import the list of man pages from the sphinx configuration to make. This will delete the (release only) target update-man-versions. This will be replaced in a followup commit.
2014-03-05 14:34:10 +01:00
install-man: ${MAN_GZIP_FILES}
doc: create manpage folders with right permissions Avoids the issue where umask can make man pages unreadable after installation. Relevant email on the mailing-list: <87h8rt30sy.fsf@fifthhorseman.net>
2018-01-31 21:50:45 +01:00
mkdir -m0755 -p "$(DESTDIR)$(mandir)/man1"
mkdir -m0755 -p "$(DESTDIR)$(mandir)/man5"
mkdir -m0755 -p "$(DESTDIR)$(mandir)/man7"
build: only install known man pages Install man pages based on $(MAN_GZIP_FILES), which directly corresponds to the man page source rst files. This way we can filter the man pages to be installed as needed.
2016-11-05 21:18:18 +01:00
install -m0644 $(filter %.1.gz,$(MAN_GZIP_FILES)) $(DESTDIR)/$(mandir)/man1
install -m0644 $(filter %.5.gz,$(MAN_GZIP_FILES)) $(DESTDIR)/$(mandir)/man5
install -m0644 $(filter %.7.gz,$(MAN_GZIP_FILES)) $(DESTDIR)/$(mandir)/man7
doc: install sphinx version of man pages The python script mkdocdeps.py is used to import the list of man pages from the sphinx configuration to make. This will delete the (release only) target update-man-versions. This will be replaced in a followup commit.
2014-03-05 14:34:10 +01:00
cd $(DESTDIR)/$(mandir)/man1 && ln -sf notmuch.1.gz notmuch-setup.1.gz
doc: configure detection of sphinx and rst2man Because sphinx-build does not provide a convenient way of listing which builders exist, and some people actually have pre 1.0 sphinx, we try loading a relevant python module. Currently the assumption is that no python in path -> no sphinx-build in path.
2014-03-13 04:21:16 +01:00
endif
doc: install sphinx version of man pages The python script mkdocdeps.py is used to import the list of man pages from the sphinx configuration to make. This will delete the (release only) target update-man-versions. This will be replaced in a followup commit.
2014-03-05 14:34:10 +01:00
doc: install build and install info pages All of the man pages are installed as info pages, plus the (unfinished) notmuch-emacs manual
2018-05-21 22:08:51 +02:00
ifneq ($(HAVE_SPHINX)$(HAVE_MAKEINFO),11)
build-info:
@echo "Missing sphinx or makeinfo, not building info pages"
else
build-info: sphinx-info
endif
ifneq ($(HAVE_SPHINX)$(HAVE_MAKEINFO)$(HAVE_INSTALL_INFO),111)
install-info:
@echo "Missing prerequisites, not installing info pages"
else
install-info: build-info
mkdir -m0755 -p "$(DESTDIR)$(infodir)"
install -m0644 $(INFO_INFO_FILES) $(DESTDIR)$(infodir)
for file in $(INFO_INFO_FILES); do install-info $$file $(DESTDIR)$(infodir)/dir; done
endif
doc: build and install doxygen api docs In order to support out of tree builds and avoid hardcoding version number, generate `doc/config.dox` from configure.
2014-07-01 18:40:33 +02:00
$(dir)/config.dox: version.stamp
echo "PROJECT_NAME = \"Notmuch $(VERSION)\"" > $@
echo "INPUT=${srcdir}/lib/notmuch.h" >> $@
doc: use stamp file to control rebuilding texi Apparently the sphinx-doc texinfo builder is not smart enough to only rebuild those files where the source has changed.
2019-04-21 18:53:03 +02:00
CLEAN := $(CLEAN) $(DOCBUILDDIR) $(DOCBUILDDIR)/.roff.stamp $(DOCBUILDDIR)/.texi.stamp
doc: use stamp file for html docs These are less time consuming than the texi docs to rebuild (because the texi rebuild triggers info rebuild), but still take noticable time.
2019-04-21 19:00:18 +02:00
CLEAN := $(CLEAN) $(DOCBUILDDIR)/.html.stamp
doc: build and install doxygen api docs In order to support out of tree builds and avoid hardcoding version number, generate `doc/config.dox` from configure.
2014-07-01 18:40:33 +02:00
CLEAN := $(CLEAN) $(MAN_GZIP_FILES) $(MAN_ROFF_FILES) $(dir)/conf.pyc $(dir)/config.dox
Reference in a new issue Copy permalink