* build and install api docs with doxygen
@ 2014-07-06 14:46 David Bremner
2014-07-06 14:46 ` [Patch v3 1/3] doc: build and install doxygen api docs David Bremner
` (2 more replies)
0 siblings, 3 replies; 9+ messages in thread
From: David Bremner @ 2014-07-06 14:46 UTC (permalink / raw)
To: notmuch
In my testing this version works ok with and without doxygen, and in
and out of tree. But I only tested in Debian jessie (testing), so other tests would be welcome.
It's a bit lame that we have to generate doxygen config file snippet
on the fly just to support out of tree builds, but doxygen seems to
have very limited support for options on the command line.
The second two patches are essentially cosmetic, although without
patch 3/3 the docs are bit eye-burningly-ugly
^ permalink raw reply [flat|nested] 9+ messages in thread* [Patch v3 1/3] doc: build and install doxygen api docs 2014-07-06 14:46 build and install api docs with doxygen David Bremner @ 2014-07-06 14:46 ` David Bremner 2014-07-06 14:46 ` [Patch v3 2/3] doc: quiet doxygen warnings David Bremner 2014-07-06 14:46 ` [Patch v3 3/3] doc: postprocess notmuch.3 David Bremner 2 siblings, 0 replies; 9+ messages in thread From: David Bremner @ 2014-07-06 14:46 UTC (permalink / raw) To: notmuch In order to support out of tree builds, generate `doc/config.dox` from configure. In order to avoid hardcoding version in doxygen.cfg, generate doc/version.dox at build time. --- configure | 18 ++++++++++++++++++ doc/Makefile.local | 26 ++++++++++++++++++++++++-- doc/doxygen.cfg | 6 +++--- 3 files changed, 45 insertions(+), 5 deletions(-) diff --git a/configure b/configure index 9514d4d..ec3a895 100755 --- a/configure +++ b/configure @@ -417,6 +417,15 @@ else have_emacs=0 fi +printf "Checking if doxygen is available... " +if doxygen -v > /dev/null 2>&1; then + printf "Yes.\n" + have_doxygen=1 +else + printf "No (so will not install api docs)\n" + have_doxygen=0 +fi + printf "Checking if sphinx is available and supports nroff output... " if hash sphinx-build > /dev/null 2>&1 && python -m sphinx.writers.manpage > /dev/null 2>&1 ; then printf "Yes.\n" @@ -725,6 +734,12 @@ commands to compile and install notmuch: EOF +# construct the Doxygen file list +cat > doc/config.dox <<EOF +# This doxgen config snippet generated by ../configure +INPUT=${srcdir}/lib/notmuch.h +EOF + # construct the Makefile.config cat > Makefile.config <<EOF # This Makefile.config was automatically generated by the ./configure @@ -829,6 +844,9 @@ HAVE_SPHINX=${have_sphinx} # Whether there's a rst2man binary available for building documentation HAVE_RST2MAN=${have_rst2man} +# Whether there's a doxygen binary available for building api documentation +HAVE_DOXYGEN=${have_doxygen} + # The directory to which desktop files should be installed desktop_dir = \$(prefix)/share/applications diff --git a/doc/Makefile.local b/doc/Makefile.local index bbd4610..618b840 100644 --- a/doc/Makefile.local +++ b/doc/Makefile.local @@ -12,10 +12,12 @@ mkdocdeps := python $(srcdir)/$(dir)/mkdocdeps.py # Internal variables. ALLSPHINXOPTS := -d $(DOCBUILDDIR)/doctrees $(SPHINXOPTS) $(srcdir)/$(dir) +APIMAN := $(DOCBUILDDIR)/man/man3/notmuch.3 +DOXYFILE := $(srcdir)/$(dir)/doxygen.cfg .PHONY: sphinx-html sphinx-texinfo sphinx-info -.PHONY: install-man build-man +.PHONY: install-man build-man apidocs install-apidocs %.gz: % rm -f $@ && gzip --stdout $^ > $@ @@ -56,6 +58,23 @@ else endif touch ${MAN_ROFF_FILES} $@ +install-man: install-apidocs + +ifeq ($(HAVE_DOXYGEN),1) +MAN_GZIP_FILES += ${APIMAN}.gz +apidocs: $(APIMAN) +install-apidocs: apidocs + mkdir -p "$(DESTDIR)$(mandir)/man3" + install -m0644 $(DOCBUILDDIR)/man/man3/*.3.gz $(DESTDIR)/$(mandir)/man3 + +$(APIMAN): $(dir)/version.dox $(srcdir)/$(dir)/doxygen.cfg $(srcdir)/lib/notmuch.h + mkdir -p $(DOCBUILDDIR)/man/man3 + doxygen $(DOXYFILE) +else +apidocs: +install-apidocs: +endif + # Do not try to build or install man pages if a man page converter is # not available. ifeq ($(HAVE_SPHINX)$(HAVE_RST2MAN),00) @@ -74,8 +93,11 @@ install-man: ${MAN_GZIP_FILES} cd $(DESTDIR)/$(mandir)/man1 && ln -sf notmuch.1.gz notmuch-setup.1.gz endif +$(dir)/version.dox: version.stamp + echo "PROJECT_NAME = \"Notmuch $(VERSION)\"" > $@ + $(dir)/docdeps.mk: $(dir)/conf.py $(dir)/mkdocdeps.py $(mkdocdeps) $(srcdir)/doc $(DOCBUILDDIR) $@ CLEAN := $(CLEAN) $(DOCBUILDDIR) $(dir)/docdeps.mk $(DOCBUILDDIR)/.roff.stamp -CLEAN := $(CLEAN) $(MAN_GZIP_FILES) $(MAN_ROFF_FILES) $(dir)/conf.pyc +CLEAN := $(CLEAN) $(MAN_GZIP_FILES) $(MAN_ROFF_FILES) $(dir)/conf.pyc $(dir)/version.dox $(dir)/config.dox diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg index bfbfcab..68e8969 100644 --- a/doc/doxygen.cfg +++ b/doc/doxygen.cfg @@ -4,11 +4,11 @@ # Project related configuration options #--------------------------------------------------------------------------- DOXYFILE_ENCODING = UTF-8 -PROJECT_NAME = "Notmuch 0.18" +@INCLUDE = "doc/version.dox" PROJECT_NUMBER = PROJECT_BRIEF = PROJECT_LOGO = -OUTPUT_DIRECTORY = +OUTPUT_DIRECTORY = doc/_build CREATE_SUBDIRS = NO OUTPUT_LANGUAGE = English BRIEF_MEMBER_DESC = YES @@ -96,7 +96,7 @@ WARN_LOGFILE = #--------------------------------------------------------------------------- # configuration options related to the input files #--------------------------------------------------------------------------- -INPUT = lib/notmuch.h +@INCLUDE = doc/config.dox INPUT_ENCODING = UTF-8 FILE_PATTERNS = RECURSIVE = NO -- 2.0.0.rc2 ^ permalink raw reply related [flat|nested] 9+ messages in thread
* [Patch v3 2/3] doc: quiet doxygen warnings 2014-07-06 14:46 build and install api docs with doxygen David Bremner 2014-07-06 14:46 ` [Patch v3 1/3] doc: build and install doxygen api docs David Bremner @ 2014-07-06 14:46 ` David Bremner 2014-07-06 14:46 ` [Patch v3 3/3] doc: postprocess notmuch.3 David Bremner 2 siblings, 0 replies; 9+ messages in thread From: David Bremner @ 2014-07-06 14:46 UTC (permalink / raw) To: notmuch remove some obsolete tags for XML output (which we don't currently generate in any case) --- doc/doxygen.cfg | 2 -- 1 file changed, 2 deletions(-) diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg index 68e8969..0f48ddb 100644 --- a/doc/doxygen.cfg +++ b/doc/doxygen.cfg @@ -228,8 +228,6 @@ MAN_LINKS = NO #--------------------------------------------------------------------------- GENERATE_XML = NO XML_OUTPUT = xml -XML_SCHEMA = -XML_DTD = XML_PROGRAMLISTING = YES #--------------------------------------------------------------------------- # configuration options related to the DOCBOOK output -- 2.0.0.rc2 ^ permalink raw reply related [flat|nested] 9+ messages in thread
* [Patch v3 3/3] doc: postprocess notmuch.3 2014-07-06 14:46 build and install api docs with doxygen David Bremner 2014-07-06 14:46 ` [Patch v3 1/3] doc: build and install doxygen api docs David Bremner 2014-07-06 14:46 ` [Patch v3 2/3] doc: quiet doxygen warnings David Bremner @ 2014-07-06 14:46 ` David Bremner 2014-07-08 23:57 ` doxygen api docs David Bremner 2 siblings, 1 reply; 9+ messages in thread From: David Bremner @ 2014-07-06 14:46 UTC (permalink / raw) To: notmuch 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. --- doc/Makefile.local | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/Makefile.local b/doc/Makefile.local index 618b840..dea20a2 100644 --- a/doc/Makefile.local +++ b/doc/Makefile.local @@ -70,6 +70,7 @@ install-apidocs: apidocs $(APIMAN): $(dir)/version.dox $(srcdir)/$(dir)/doxygen.cfg $(srcdir)/lib/notmuch.h mkdir -p $(DOCBUILDDIR)/man/man3 doxygen $(DOXYFILE) + perl -pi -e 's/^[.]RI "\\fI/.RI "\\fP/' $(APIMAN) else apidocs: install-apidocs: -- 2.0.0.rc2 ^ permalink raw reply related [flat|nested] 9+ messages in thread
* doxygen api docs 2014-07-06 14:46 ` [Patch v3 3/3] doc: postprocess notmuch.3 David Bremner @ 2014-07-08 23:57 ` David Bremner 2014-07-08 23:57 ` [Patch v4 1/3] doc: build and install " David Bremner ` (2 more replies) 0 siblings, 3 replies; 9+ messages in thread From: David Bremner @ 2014-07-08 23:57 UTC (permalink / raw) To: notmuch In this version, I took Tomi's suggestion on IRC, and generate the (single) doxygen config snippet from the makefile. ^ permalink raw reply [flat|nested] 9+ messages in thread
* [Patch v4 1/3] doc: build and install doxygen api docs 2014-07-08 23:57 ` doxygen api docs David Bremner @ 2014-07-08 23:57 ` David Bremner 2014-07-09 20:22 ` Tomi Ollila 2014-07-08 23:57 ` [Patch v4 2/3] doc: quiet doxygen warnings David Bremner 2014-07-08 23:57 ` [Patch v4 3/3] doc: postprocess notmuch.3 David Bremner 2 siblings, 1 reply; 9+ messages in thread From: David Bremner @ 2014-07-08 23:57 UTC (permalink / raw) To: notmuch In order to support out of tree builds, generate `doc/config.dox` from configure. In order to avoid hardcoding version in doxygen.cfg, generate doc/version.dox at build time. --- configure | 12 ++++++++++++ doc/Makefile.local | 27 +++++++++++++++++++++++++-- doc/doxygen.cfg | 5 ++--- 3 files changed, 39 insertions(+), 5 deletions(-) diff --git a/configure b/configure index 9514d4d..fa44188 100755 --- a/configure +++ b/configure @@ -417,6 +417,15 @@ else have_emacs=0 fi +printf "Checking if doxygen is available... " +if doxygen -v > /dev/null 2>&1; then + printf "Yes.\n" + have_doxygen=1 +else + printf "No (so will not install api docs)\n" + have_doxygen=0 +fi + printf "Checking if sphinx is available and supports nroff output... " if hash sphinx-build > /dev/null 2>&1 && python -m sphinx.writers.manpage > /dev/null 2>&1 ; then printf "Yes.\n" @@ -829,6 +838,9 @@ HAVE_SPHINX=${have_sphinx} # Whether there's a rst2man binary available for building documentation HAVE_RST2MAN=${have_rst2man} +# Whether there's a doxygen binary available for building api documentation +HAVE_DOXYGEN=${have_doxygen} + # The directory to which desktop files should be installed desktop_dir = \$(prefix)/share/applications diff --git a/doc/Makefile.local b/doc/Makefile.local index bbd4610..72b8f68 100644 --- a/doc/Makefile.local +++ b/doc/Makefile.local @@ -12,10 +12,12 @@ mkdocdeps := python $(srcdir)/$(dir)/mkdocdeps.py # Internal variables. ALLSPHINXOPTS := -d $(DOCBUILDDIR)/doctrees $(SPHINXOPTS) $(srcdir)/$(dir) +APIMAN := $(DOCBUILDDIR)/man/man3/notmuch.3 +DOXYFILE := $(srcdir)/$(dir)/doxygen.cfg .PHONY: sphinx-html sphinx-texinfo sphinx-info -.PHONY: install-man build-man +.PHONY: install-man build-man apidocs install-apidocs %.gz: % rm -f $@ && gzip --stdout $^ > $@ @@ -56,6 +58,23 @@ else endif touch ${MAN_ROFF_FILES} $@ +install-man: install-apidocs + +ifeq ($(HAVE_DOXYGEN),1) +MAN_GZIP_FILES += ${APIMAN}.gz +apidocs: $(APIMAN) +install-apidocs: apidocs + mkdir -p "$(DESTDIR)$(mandir)/man3" + install -m0644 $(DOCBUILDDIR)/man/man3/*.3.gz $(DESTDIR)/$(mandir)/man3 + +$(APIMAN): $(dir)/config.dox $(srcdir)/$(dir)/doxygen.cfg $(srcdir)/lib/notmuch.h + mkdir -p $(DOCBUILDDIR)/man/man3 + doxygen $(DOXYFILE) +else +apidocs: +install-apidocs: +endif + # Do not try to build or install man pages if a man page converter is # not available. ifeq ($(HAVE_SPHINX)$(HAVE_RST2MAN),00) @@ -74,8 +93,12 @@ install-man: ${MAN_GZIP_FILES} cd $(DESTDIR)/$(mandir)/man1 && ln -sf notmuch.1.gz notmuch-setup.1.gz endif +$(dir)/config.dox: version.stamp + echo "PROJECT_NAME = \"Notmuch $(VERSION)\"" > $@ + echo "INPUT=${srcdir}/lib/notmuch.h" >> $@ + $(dir)/docdeps.mk: $(dir)/conf.py $(dir)/mkdocdeps.py $(mkdocdeps) $(srcdir)/doc $(DOCBUILDDIR) $@ CLEAN := $(CLEAN) $(DOCBUILDDIR) $(dir)/docdeps.mk $(DOCBUILDDIR)/.roff.stamp -CLEAN := $(CLEAN) $(MAN_GZIP_FILES) $(MAN_ROFF_FILES) $(dir)/conf.pyc +CLEAN := $(CLEAN) $(MAN_GZIP_FILES) $(MAN_ROFF_FILES) $(dir)/conf.pyc $(dir)/config.dox diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg index bfbfcab..1a53af5 100644 --- a/doc/doxygen.cfg +++ b/doc/doxygen.cfg @@ -4,11 +4,11 @@ # Project related configuration options #--------------------------------------------------------------------------- DOXYFILE_ENCODING = UTF-8 -PROJECT_NAME = "Notmuch 0.18" +@INCLUDE = "doc/config.dox" PROJECT_NUMBER = PROJECT_BRIEF = PROJECT_LOGO = -OUTPUT_DIRECTORY = +OUTPUT_DIRECTORY = doc/_build CREATE_SUBDIRS = NO OUTPUT_LANGUAGE = English BRIEF_MEMBER_DESC = YES @@ -96,7 +96,6 @@ WARN_LOGFILE = #--------------------------------------------------------------------------- # configuration options related to the input files #--------------------------------------------------------------------------- -INPUT = lib/notmuch.h INPUT_ENCODING = UTF-8 FILE_PATTERNS = RECURSIVE = NO -- 2.0.0.rc2 ^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [Patch v4 1/3] doc: build and install doxygen api docs 2014-07-08 23:57 ` [Patch v4 1/3] doc: build and install " David Bremner @ 2014-07-09 20:22 ` Tomi Ollila 0 siblings, 0 replies; 9+ messages in thread From: Tomi Ollila @ 2014-07-09 20:22 UTC (permalink / raw) To: David Bremner, notmuch On Wed, Jul 09 2014, David Bremner <david@tethera.net> wrote: > In order to support out of tree builds, generate `doc/config.dox` from > configure. > > In order to avoid hardcoding version in doxygen.cfg, generate > doc/version.dox at build time. is this commit message accurate ? > --- > configure | 12 ++++++++++++ > doc/Makefile.local | 27 +++++++++++++++++++++++++-- > doc/doxygen.cfg | 5 ++--- > 3 files changed, 39 insertions(+), 5 deletions(-) > > diff --git a/configure b/configure > index 9514d4d..fa44188 100755 > --- a/configure > +++ b/configure > @@ -417,6 +417,15 @@ else > have_emacs=0 > fi > > +printf "Checking if doxygen is available... " > +if doxygen -v > /dev/null 2>&1; then Doxygen 1.6.1 does not know -v -- and exits w/ value 1. If we wanted to allow man generation using that version (out-of-the-box) then the line above should be `if command -v doxygen >/dev/null; then` otherwise this series looks good and generation seems to work. Tomi > + printf "Yes.\n" > + have_doxygen=1 > +else > + printf "No (so will not install api docs)\n" > + have_doxygen=0 > +fi > + ^ permalink raw reply [flat|nested] 9+ messages in thread
* [Patch v4 2/3] doc: quiet doxygen warnings 2014-07-08 23:57 ` doxygen api docs David Bremner 2014-07-08 23:57 ` [Patch v4 1/3] doc: build and install " David Bremner @ 2014-07-08 23:57 ` David Bremner 2014-07-08 23:57 ` [Patch v4 3/3] doc: postprocess notmuch.3 David Bremner 2 siblings, 0 replies; 9+ messages in thread From: David Bremner @ 2014-07-08 23:57 UTC (permalink / raw) To: notmuch remove some obsolete tags for XML output (which we don't currently generate in any case) --- doc/doxygen.cfg | 2 -- 1 file changed, 2 deletions(-) diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg index 1a53af5..42b6339 100644 --- a/doc/doxygen.cfg +++ b/doc/doxygen.cfg @@ -227,8 +227,6 @@ MAN_LINKS = NO #--------------------------------------------------------------------------- GENERATE_XML = NO XML_OUTPUT = xml -XML_SCHEMA = -XML_DTD = XML_PROGRAMLISTING = YES #--------------------------------------------------------------------------- # configuration options related to the DOCBOOK output -- 2.0.0.rc2 ^ permalink raw reply related [flat|nested] 9+ messages in thread
* [Patch v4 3/3] doc: postprocess notmuch.3 2014-07-08 23:57 ` doxygen api docs David Bremner 2014-07-08 23:57 ` [Patch v4 1/3] doc: build and install " David Bremner 2014-07-08 23:57 ` [Patch v4 2/3] doc: quiet doxygen warnings David Bremner @ 2014-07-08 23:57 ` David Bremner 2 siblings, 0 replies; 9+ messages in thread From: David Bremner @ 2014-07-08 23:57 UTC (permalink / raw) To: notmuch 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. --- doc/Makefile.local | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/Makefile.local b/doc/Makefile.local index 72b8f68..9b6cfe5 100644 --- a/doc/Makefile.local +++ b/doc/Makefile.local @@ -70,6 +70,7 @@ install-apidocs: apidocs $(APIMAN): $(dir)/config.dox $(srcdir)/$(dir)/doxygen.cfg $(srcdir)/lib/notmuch.h mkdir -p $(DOCBUILDDIR)/man/man3 doxygen $(DOXYFILE) + perl -pi -e 's/^[.]RI "\\fI/.RI "\\fP/' $(APIMAN) else apidocs: install-apidocs: -- 2.0.0.rc2 ^ permalink raw reply related [flat|nested] 9+ messages in thread
end of thread, other threads:[~2014-07-09 20:23 UTC | newest] Thread overview: 9+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2014-07-06 14:46 build and install api docs with doxygen David Bremner 2014-07-06 14:46 ` [Patch v3 1/3] doc: build and install doxygen api docs David Bremner 2014-07-06 14:46 ` [Patch v3 2/3] doc: quiet doxygen warnings David Bremner 2014-07-06 14:46 ` [Patch v3 3/3] doc: postprocess notmuch.3 David Bremner 2014-07-08 23:57 ` doxygen api docs David Bremner 2014-07-08 23:57 ` [Patch v4 1/3] doc: build and install " David Bremner 2014-07-09 20:22 ` Tomi Ollila 2014-07-08 23:57 ` [Patch v4 2/3] doc: quiet doxygen warnings David Bremner 2014-07-08 23:57 ` [Patch v4 3/3] doc: postprocess notmuch.3 David Bremner
Code repositories for project(s) associated with this public inbox https://yhetil.org/notmuch.git/ This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).