build and install api docs with doxygen

build and install api docs with doxygen

[David Bremner]

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

[Patch v3 1/3] doc: build and install doxygen api docs

[David Bremner]

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

[Patch v3 2/3] doc: quiet doxygen warnings

[David Bremner]

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

[Patch v3 3/3] doc: postprocess notmuch.3

[David Bremner]

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

doxygen api docs

[David Bremner]

In this version, I took Tomi's suggestion on IRC, and generate the
(single) doxygen config snippet from the makefile.

[Patch v4 1/3] doc: build and install doxygen api docs

[David Bremner]

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

[Patch v4 2/3] doc: quiet doxygen warnings

[David Bremner]

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

[Patch v4 3/3] doc: postprocess notmuch.3

[David Bremner]

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

Re: [Patch v4 1/3] doc: build and install doxygen api docs

[Tomi Ollila]

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
> +