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

164 lines
5.6 KiB
Text
Raw Normal View History

emacs: Use makefile-gmake-mode in Makefile*s Use `makefile-gmake-mode' instead of `makefile-mode' because the former also highlights ifdef et al. while the latter does not. "./Makefile.global" and one "Makefile.local" failed to specify any major mode at all but doing so is necessary because Emacs does not automatically figure out that these are Makefiles (of any flavor).
2020-08-08 13:49:49 +02:00
# -*- makefile-gmake -*-
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
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/python-cffi: import from built bindings, not installed module Previously the python-cffi bindings either failed to build, or built for the wrong module by using the installed module. The fix requires correction the module path, building the bindings before docs, and helping python find the built libnotmuch. Based on patch / discussion from Micheal Gruber [1] [1]: id:cover.1634808719.git.git@grubix.eu
2021-10-29 16:54:59 +02:00
SPHINXBUILD = env LD_LIBRARY_PATH=${NOTMUCH_BUILDDIR}/lib 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
doc: replace symlink with copies for nmbug, notmuch-setup Previously only man page aliases were being added as symlinks. The addition to man_pages in conf.py automatically propagates to the list of generated info pages. Installation of the new pages is handled by existing recipes.
2022-07-01 03:14:20 +02:00
COPY_ROFF1 := $(patsubst %,$(DOCBUILDDIR)/man/man1/%.1,nmbug notmuch-setup)
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))
doc: replace symlink with copies for nmbug, notmuch-setup Previously only man page aliases were being added as symlinks. The addition to man_pages in conf.py automatically propagates to the list of generated info pages. Installation of the new pages is handled by existing recipes.
2022-07-01 03:14:20 +02:00
MAN1_ROFF := $(MAN1_ROFF) $(COPY_ROFF1)
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
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))
doc: Don't install emacs docs when they are not built In 40b025 we stopped building the notmuch-emacs documentation if HAVE_EMACS=0 (i.e. no emacs was detected by configure). Unfortunately we continued to try to install the (non-existent) documentation, which causes build/install failures. As a bonus, we also avoid installing the documentation if the user configures --without-emacs. Thanks to Ralph Seichter for reporting the problem, and testing previous versions of this fix.
2019-06-10 12:11:50 +02:00
INFO_TEXI_FILES := $(MAN1_TEXI) $(MAN5_TEXI) $(MAN7_TEXI)
build: drop variable HAVE_EMACS. use WITH_EMACS instead The extra flexibility of having both HAVE_EMACS (for yes, there is an emacs we can use) and WITH_EMACS (the user wants emacs support) lead to confusion and bugs. We now just force WITH_EMACS to 0 if no suitable emacs is detected.
2019-06-12 02:12:38 +02:00
ifeq ($(WITH_EMACS),1)
INFO_TEXI_FILES += $(DOCBUILDDIR)/texinfo/notmuch-emacs.texi
doc: Don't install emacs docs when they are not built In 40b025 we stopped building the notmuch-emacs documentation if HAVE_EMACS=0 (i.e. no emacs was detected by configure). Unfortunately we continued to try to install the (non-existent) documentation, which causes build/install failures. As a bonus, we also avoid installing the documentation if the user configures --without-emacs. Thanks to Ralph Seichter for reporting the problem, and testing previous versions of this fix.
2019-06-10 12:11:50 +02:00
endif
doc: replace symlink with copies for nmbug, notmuch-setup Previously only man page aliases were being added as symlinks. The addition to man_pages in conf.py automatically propagates to the list of generated info pages. Installation of the new pages is handled by existing recipes.
2022-07-01 03:14:20 +02:00
COPY_INFO1 := $(patsubst $(DOCBUILDDIR)/man/man1/%.1,$(DOCBUILDDIR)/texinfo/%.info,$(COPY_ROFF1))
INFO_INFO_FILES := $(INFO_TEXI_FILES:.texi=.info) $(COPY_INFO1)
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
doc: replace phony target with variable Depending on a phony target seems like a good way to always trigger a recipe.
2021-12-05 00:47:50 +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: %
doc: make gzipped man pages reproducible gzip includes the name of the uncompressed file and its modification timestamp into the compressed archive. The latter makes it hard to reproduce the generated files bit for bit at a later time, so omit this information from the archive using the "--no-name" option. This is a reproducibility best practice, see https://wiki.debian.org/ReproducibleBuilds/TimestampsInGzipHeaders
2020-07-11 18:04:35 +02:00
rm -f $@ && gzip --no-name --stdout $^ > $@
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/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)
build/docs: move docstring prereq to file targets Under a sufficiently high level of parallelism [1] there seems to be a a race condition that allows sphinx-build to start running before the docstrings are extracted. This change moves the docstring stamp from the phony targets sphinx-html and sphinx-info to the file targets that they depend on. I'm not sure why this makes things better, but I am fairly confident it does not make things worse, and experimentally it seems to eliminate the race condition. [1]: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=976934
2020-12-10 02:55:38 +01:00
$(DOCBUILDDIR)/.roff.stamp $(DOCBUILDDIR)/.html.stamp $(DOCBUILDDIR)/.texi.stamp : 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/python-cffi: import from built bindings, not installed module Previously the python-cffi bindings either failed to build, or built for the wrong module by using the installed module. The fix requires correction the module path, building the bindings before docs, and helping python find the built libnotmuch. Based on patch / discussion from Micheal Gruber [1] [1]: id:cover.1634808719.git.git@grubix.eu
2021-10-29 16:54:59 +02:00
ifeq ($(HAVE_PYTHON3_CFFI),1)
doc: replace phony target with variable Depending on a phony target seems like a good way to always trigger a recipe.
2021-12-05 00:47:50 +01:00
DOC_PREREQS=bindings/python-cffi.stamp
else
DOC_PREREQS=
doc/python-cffi: import from built bindings, not installed module Previously the python-cffi bindings either failed to build, or built for the wrong module by using the installed module. The fix requires correction the module path, building the bindings before docs, and helping python find the built libnotmuch. Based on patch / discussion from Micheal Gruber [1] [1]: id:cover.1634808719.git.git@grubix.eu
2021-10-29 16:54:59 +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
doc: replace phony target with variable Depending on a phony target seems like a good way to always trigger a recipe.
2021-12-05 00:47:50 +01:00
$(DOCBUILDDIR)/.html.stamp: $(ALL_RST_FILES) $(DOC_PREREQS)
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
doc: replace phony target with variable Depending on a phony target seems like a good way to always trigger a recipe.
2021-12-05 00:47:50 +01:00
$(DOCBUILDDIR)/.texi.stamp: $(ALL_RST_FILES) $(DOC_PREREQS)
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
doc: introduce stamp file for info build This partially fixes (i.e. just for sphinx) the problem reported by Daniel in id:87r29wwgq2.fsf@fifthhorseman.net.
2021-12-05 00:47:51 +01:00
sphinx-info: $(DOCBUILDDIR)/.info.stamp
$(DOCBUILDDIR)/.info.stamp: $(DOCBUILDDIR)/.texi.stamp $(DOC_PREREQS)
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: introduce stamp file for info build This partially fixes (i.e. just for sphinx) the problem reported by Daniel in id:87r29wwgq2.fsf@fifthhorseman.net.
2021-12-05 00:47:51 +01: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: 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
doc: add dep. on stamp file for rebuilding gzipped man pages. In [1] Daniel observed that the gzipped man pages were only being rebuild every second time when building with `make -j4'. This may be caused by a race condition between sphinx-build rebuilding the roff files and the recipe to gzip them. This commit sequentializes these two steps by making the stamp file a prerequisite for (all of) the gzip files. [1]: id:87tveotn1g.fsf@fifthhorseman.net
2021-12-24 17:20:31 +01:00
# it should be safe to depend on the stamp file, because it is created
# after all roff files are moved into place.
${MAN_GZIP_FILES}: ${DOCBUILDDIR}/.roff.stamp
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: ${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: 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
doc: introduce stamp file for info build This partially fixes (i.e. just for sphinx) the problem reported by Daniel in id:87r29wwgq2.fsf@fifthhorseman.net.
2021-12-05 00:47:51 +01:00
build-info: $(DOCBUILDDIR)/.info.stamp
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
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: introduce stamp file for info build This partially fixes (i.e. just for sphinx) the problem reported by Daniel in id:87r29wwgq2.fsf@fifthhorseman.net.
2021-12-05 00:47:51 +01:00
CLEAN := $(CLEAN) $(DOCBUILDDIR)/.html.stamp $(DOCBUILDDIR)/.info.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
build: clean up __pycache__ directories These are generated indirectly by certain uses of python in the build.
2023-09-11 01:13:13 +02:00
CLEAN := $(CLEAN) $(dir)/__pycache__
Reference in a new issue Copy permalink