Re: [PATCH 2/2] doc: build and install doxygen api docs

Subject: Re: [PATCH 2/2] doc: build and install doxygen api docs

Date: Sun, 06 Apr 2014 10:57:08 +0300

To: David Bremner, notmuch@notmuchmail.org

Cc:

From: Tomi Ollila

On Sun, Apr 06 2014, David Bremner <david@tethera.net> wrote:

> Add to the build-man and install-man targets. We also stop hardcoding
> the version information into doxygen.cfg
> ---
>  doc/Makefile.local | 14 ++++++++++++--
>  doc/doxygen.cfg    |  4 ++--
>  2 files changed, 14 insertions(+), 4 deletions(-)
>
> diff --git a/doc/Makefile.local b/doc/Makefile.local
> index 0980c71..5189f97 100644
> --- a/doc/Makefile.local
> +++ b/doc/Makefile.local
> @@ -12,6 +12,8 @@ mkdocdeps := python $(srcdir)/$(dir)/mkdocdeps.py
>  
>  # Internal variables.
>  ALLSPHINXOPTS   := -d $(DOCBUILDDIR)/doctrees $(SPHINXOPTS) $(srcdir)/$(dir)
> +APIMAN		:= $(DOCBUILDDIR)/man/man3/notmuch.3
> +DOXYFILE	:= $(dir)/doxygen.cfg
>  
>  .PHONY: sphinx-html sphinx-texinfo sphinx-info
>  
> @@ -31,7 +33,7 @@ sphinx-info: sphinx-texinfo
>  
>  -include $(dir)/docdeps.mk
>  
> -MAN_GZIP_FILES := $(addsuffix .gz,${MAN_ROFF_FILES})
> +MAN_GZIP_FILES := $(addsuffix .gz,${MAN_ROFF_FILES} ${APIMAN})
>  
>  # Use the man page converter that is available. We should never depend
>  # on MAN_ROFF_FILES if a converter is not available.
> @@ -59,16 +61,24 @@ else
>  build-man: ${MAN_GZIP_FILES}
>  install-man: ${MAN_GZIP_FILES}
>  	mkdir -p "$(DESTDIR)$(mandir)/man1"
> +	mkdir -p "$(DESTDIR)$(mandir)/man3"
>  	mkdir -p "$(DESTDIR)$(mandir)/man5"
>  	mkdir -p "$(DESTDIR)$(mandir)/man7"
>  	install -m0644 $(DOCBUILDDIR)/man/man1/*.1.gz $(DESTDIR)/$(mandir)/man1
> +	install -m0644 $(DOCBUILDDIR)/man/man3/*.3.gz $(DESTDIR)/$(mandir)/man3
>  	install -m0644 $(DOCBUILDDIR)/man/man5/*.5.gz $(DESTDIR)/$(mandir)/man5
>  	install -m0644 $(DOCBUILDDIR)/man/man7/*.7.gz $(DESTDIR)/$(mandir)/man7
>  	cd $(DESTDIR)/$(mandir)/man1 && ln -sf notmuch.1.gz notmuch-setup.1.gz
>  endif
>  
> +$(APIMAN): $(dir)/version.dox $(dir)/doxygen.cfg $(srcdir)/lib/notmuch.h
> +	doxygen $(DOXYFILE)
> +
> +$(dir)/version.dox: $(srcdir)/version
> +	sed -e 's/^/PROJECT_NAME = \"Notmuch /' -e 's/$$/\"/' < $< > $@
> +

LGTM, although:

      echo "PROJECT_NAME = \"Notmuch `cat $<`\"" >$@

no, 

      echo 'PROJECT_NAME = "Notmuch $(VERSION)"' > $@


... and, the dependency should be to version.stamp (w/o $(srcdir)) after

id:1395261431-24668-1b-git-send-email-tomi.ollila@iki.fi is merged :D

... as especially developers need to know the exact version they have
in their git tree instead of last released one.

I marked my patch in this thread obsolete (my previous statement makes this
obvious) and 1/1 on this series ready.

Tomi



>  $(dir)/docdeps.mk: $(dir)/conf.py $(dir)/mkdocdeps.py
>  	$(mkdocdeps) $(srcdir)/doc $(DOCBUILDDIR) $@
>  
>  CLEAN := $(CLEAN) $(DOCBUILDDIR) $(dir)/docdeps.mk $(dir)/man.stamp
> -CLEAN := $(CLEAN) $(MAN_GZIP_FILES) $(MAN_ROFF_FILES)
> +CLEAN := $(CLEAN) $(MAN_GZIP_FILES) $(MAN_ROFF_FILES) $(dir)/version.dox
> diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg
> index 65d5fb5..bf9f075 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.17"
> +@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
> -- 
> 1.9.0

Thread: