[beast: 138/144] DOCS: incorporate api doc build rule improvements from Rapicorn

[Tim Janik <timj src gnome org>]

commit 4190bd0bcc529478ffe3e3ab97c93b66b074056e
Author: Tim Janik <timj gnu org>
Date:   Fri Jan 18 03:29:52 2013 +0100

    DOCS: incorporate api doc build rule improvements from Rapicorn

 docs/dev/makefile |  100 ++++++++++++++++++++++++++++++++++++++---------------
 1 files changed, 72 insertions(+), 28 deletions(-)
---
diff --git a/docs/dev/makefile b/docs/dev/makefile
index c6753e9..0ed2952 100644
--- a/docs/dev/makefile
+++ b/docs/dev/makefile
@@ -1,54 +1,98 @@
 # Build and upload development documentation
 
 all: build-stamp
+build-stamp:
+	$(MAKE) all-docs
+	touch $@
 
 top_srcdir  = ../..
-git_stamp   = $(top_srcdir)/.git/$(shell git symbolic-ref -q HEAD)
-SED_VERSION = $(shell sed -ne "/^[ \t]*VERSION[ \t]*=/ { s/^[^=]*=[ \t]*//; p; q }" < $(top_srcdir)/Makefile)
+git_stamp   = $(wildcard $(top_srcdir)/.git/$(shell git symbolic-ref -q HEAD) $(top_srcdir)/.git/packed-refs)
+REL_VERSION   = $(shell git describe --always --abbrev=0 HEAD 2>/dev/null)
+DSC_VERSION   = $(shell git describe --always --match '[0-9]*' HEAD 2>/dev/null)
+PRJ_VERSION   = $(shell sed -ne "/^[ \t]*VERSION[ \t]*=/ { s/^[^=]*=[ \t]*//; p; q }" < $(top_srcdir)/Makefile)
+DOC_VERSION = $(or $(DSC_VERSION), $(PRJ_VERSION))
 SED_MKEVEN  = sed 's/1$$/0/;s/3$$/2/;s/5$$/4/;s/7$$/6/;s/9$$/8/'
 
 DOC_DIRS   = birnet/ sfi/ bse/ plugins/ plugins/freeverb/ beast-gtk/ beast-gtk/gxk/ launchers/ shell/ tools/
-DOCU_GLOBS = *.idl *.h *.H *.hh *.proc
-DOXY_GLOBS = $(DOCU_GLOBS) *.c *.C *.cc
-SRCTREE    = srctree
+DOCU_GLOBS  = *.dox *.py $(DOCU_HGLOBS)
+DOCU_HGLOBS = *.idl *.h *.H *.hh *.proc
+DOCU_CGLOBS = $(DOCU_GLOBS) *.c *.C *.cc
+SRCTREE     = srctree
+DOXYGENV    = doxygen-1.7.4
+DOXYGEN     = $(if $(shell which $(DOXYGENV)), $(DOXYGENV), doxygen)
+GPRINT	    = @printf '  %-7s%s\n'
+Q           = $(if $(findstring 1, $(V)) ,, @)
+QSTDOUT     = $(Q:@=1>/dev/null)
+QSTDERR     = $(Q:@=2>/dev/null)
+
+EXCLUDES = rope/cpy2rope.cc rope/cxx-client.[hc][hc] rcore/signalvariants.hh
+
+CHANGELOG_PGT = "BEAST Development ChangeLog"
+CHANGELOG_SED = -e 's/(@\w)/\\\1/g; s/&/\&amp;/g; s/</\&lt;/g; s/>/\&gt;/g; s,\*/,*\&nbps;/,g' \
+		-e '/^[^ ].*\# [0-9a-f]/s/^(.*)\# ([0-9a-f]+)/@section commit_\2 \0/' \
+		-e 's/^[ \t]+\*? ?([a-zA-Z0-9_.+\/-]+):[ \t]*(\w.*)$$/- @b \1: \2/' \
+		-e 's/^[ \t]+\*? ?([a-zA-Z0-9_.+\/-]+):(.*)/- <em><b>\1:<\/b> \2<\/em>/' \
+		-e 's/^/ * /'
 
 .PHONY: $(SRCTREE)
 $(SRCTREE):
-	rm -rf $(SRCTREE)/
-	mkdir -p $(SRCTREE)/
-	@echo "### Copying Source..."
-	CWD=`pwd` \
+	$(GPRINT) "GEN" $(SRCTREE)/
+	$(Q) rm -rf $(SRCTREE)/ && mkdir -p $(SRCTREE)/
+	$(GPRINT) "GEN" "ChangeLog"
+	$(Q) test -f $(top_srcdir)/ChangeLog || { echo "Missing $(top_srcdir)/ChangeLog" >&2 ; false ; }
+	$(Q) echo '/*! @page ChangeLog' $(CHANGELOG_PGT)	 > $(SRCTREE)/ChangeLog
+	$(Q) sed -r $(CHANGELOG_SED) <$(top_srcdir)/ChangeLog	>> $(SRCTREE)/ChangeLog
+	$(Q) echo ' */' 					>> $(SRCTREE)/ChangeLog
+	$(GPRINT) "COPY" "Source tree..." \
+	&& CWD=`pwd` \
 	&& for dir in $(DOC_DIRS) ; do \
 	  (mkdir -p $$CWD/$(SRCTREE)/$$dir/ \
 	   && cd $(top_srcdir)/$$dir \
-	   && find . -maxdepth 1 -type f \( $(patsubst %,-name '%' -o, $(DOXY_GLOBS)) -false \) \
-	      -exec cp {} $$CWD/$(SRCTREE)/$$dir/{} \; ) \
+	   && find . -maxdepth 1 -type f \( $(patsubst %,-name '%' -o, $(DOCU_CGLOBS)) -false \) \
+	      -exec cp {} $$CWD/$(SRCTREE)/$$dir/{} \; ) || exit $? ; \
 	  done
-	@echo "### Identifying Documentation files..."
-	cd $(SRCTREE)/ \
+	$(GPRINT) "ADD" "File docu commands..." \
+	&& cd $(SRCTREE)/ \
 	&& find . -type f \( $(patsubst %,-name '%' -o, $(DOCU_GLOBS)) -false \) \
 	   -exec sed  '1,+0s,^,/** @file {} */,' {} --in-place \;
 
+LINK_PROJECT_NAME = \
+	-e 's|<div id="projectname">BEAST/BSE|<div id="projectname"><a href="http://beast.testbit.eu";>BEAST/BSE</a>|'
+R_ACCESSKEY_AS_F = -e 's/(<input [^>]*id="MSearchField"[^>]*accesskey=")S"/\1F"/'
 
-build-stamp: $(git_stamp) doxygen.cfg
-	rm -rf html/
-	mkdir -p html/
-	$(MAKE) $(SRCTREE)
-	@echo "### Doxygen..."
-	(cat doxygen.cfg \
+all-docs: $(git_stamp) doxygen.cfg
+	$(GPRINT) "TIDY" "Temporaries..."
+	$(Q) rm -rf html.tmp/ && mkdir -p html.tmp/
+	$(Q) $(MAKE) $(SRCTREE)
+	$(GPRINT) "GEN" "HTML Documentation..."
+	$(Q) (cat doxygen.cfg \
 	&& echo "STRIP_FROM_PATH  = `pwd`/$(SRCTREE)" \
 	&& echo "INPUT		  = $(SRCTREE)/" \
-	&& echo "OUTPUT_DIRECTORY = html/" \
-	&& echo -n "PROJECT_NUMBER = $(SED_VERSION)" \
-	) | nice doxygen -
-	rm -rf $(SRCTREE)/
-	mv html/html/ html/$(SED_VERSION)/
-	ln -s $(SED_VERSION) html/latest
-	touch $@
+	&& echo "EXAMPLE_PATH	  = $(top_srcdir)/" \
+	&& echo "OUTPUT_DIRECTORY = html.tmp/" \
+	&& echo -n "PROJECT_NUMBER = $(PRJ_VERSION)" \
+	) | nice $(DOXYGEN) - >error.log 2>&1
+	$(Q) test ! -s error.log && rm -f error.log \
+	|| { echo "WARNING: doxygen issues encountered ($$(wc -l <error.log)): $$(pwd)/error.log" ; cat error.log $(QSTDOUT) ; }
+	$(GPRINT) "POLISH" "HTML Files..."
+	$(Q) sed $(LINK_PROJECT_NAME) -i html.tmp/html/*.html
+	$(Q) sed -r $(R_ACCESSKEY_AS_F) -i html.tmp/html/*.html
+	$(Q) mv html.tmp/html/ html.tmp/$(DOC_VERSION)/
+	$(Q) ln -s $(DOC_VERSION) html.tmp/latest
+	$(GPRINT) "RSYNC" "HTML Documentation..."
+	$(Q) rsync -aH --del html.tmp/ html/
+	$(GPRINT) "CLEAN" "Temporaries..."
+	$(Q) rm -rf $(SRCTREE)/ html.tmp/
 
+# upload release versions directly, otherwise upload as latest/
 upload: all
-	rsync -aHP --del '--filter=P /*/' html/  dev.testbit.eu:/srv/dev/html/beast/
+	$(Q) test "${REL_VERSION}" != "${DSC_VERSION}" || { set -x ; \
+	  rsync -zaHP --del "html/${DOC_VERSION}"  "testbit:/srv/dev/html/beast/${DOC_VERSION}" ; }
+	$(Q) test "${REL_VERSION}" = "${DSC_VERSION}" || { set -x ; \
+	  rsync -zaHP --del "html/${DOC_VERSION}/"  "testbit:/srv/dev/html/beast/latest/" ; }
 
 clean:
 	rm -f build-stamp
-	rm -rf $(SRCTREE)/ html/
+	rm -rf $(SRCTREE)/ html.tmp/
+	rm -rf html/
+maintainer-clean: clean