unofficial mirror of notmuch@notmuchmail.org
 help / color / mirror / code / Atom feed
* 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

* [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

* 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

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).