[beast: 7/9] DOCS: add 'make docs' rule to (slowly) build rich docs for the website

[Tim Janik <timj src gnome org>]

commit d6198b38de611b01d0c0ddb524b0913806c8bb2e
Author: Tim Janik <timj gnu org>
Date:   Sat Jul 1 22:06:12 2017 +0200

    DOCS: add 'make docs' rule to (slowly) build rich docs for the website
    
    Signed-off-by: Tim Janik <timj gnu org>

 docs/Makefile.am |   25 +++++++++++++++----------
 docs/doxygen.cfg |   34 +++++++++++++++++++++-------------
 2 files changed, 36 insertions(+), 23 deletions(-)
---
diff --git a/docs/Makefile.am b/docs/Makefile.am
index fe0e268..f64349a 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -3,7 +3,6 @@ include $(top_srcdir)/Makefile.decl
 
 SUBDIRS = images
 
-MOSTLYCLEANFILES =
 beastmandir = ${beastsharedir}/man
 man1dir     = $(beastmandir)/man1
 man1_MANS   =
@@ -46,9 +45,6 @@ docs_doxygen_werror = false
 docs_upload_name    = $(shell test "`git describe --match '[0-9]*.*[0-9]' 2>/dev/null`" = "`git describe 
--long 2>/dev/null`" \
                        && echo latest || echo ${MAJOR}.${MINOR})
 
-# Build with dot files by default
-DOXYGEN_GRAPHICS  ?= NO # YES
-
 # == docs/srctree ==
 doxy/src: $(patsubst %, ../%, $(docs_doxy_sources) $(docs_doxy_extra) $(docs_doxygen_tagbzs)) | 
collect_docs_doxy_sources
        $(AM_V_GEN)
@@ -75,14 +71,11 @@ doxy/html: $(if $(NODOC), , ../topbuildid.cc)
 # use order-only prerequisite on docs/doxy/src to spare doxygen runs for source edits
 doxy/html: ../docs/doxygen.cfg ../docs/error.ign $(docs_doxy_auxfiles) | doxy/src
        $(V_gen) "PREPARE" $@
-       $(Q) rm -Rf doxy/html doxy/output
+       $(Q) rm -Rf doxy/html doxy/output doxy/richdocs
        $(Q) mkdir -p doxy/output
        $(Q) cp $(docs_doxy_auxfiles) doxy/
-       $(Q) (cat ../docs/doxygen.cfg \
+       $(Q) (sed $(RICHDOCS_SED) ../docs/doxygen.cfg \
        && echo "PROJECT_NUMBER         = $(topbuildid)" \
-       && echo "HAVE_DOT               = $(DOXYGEN_GRAPHICS)" \
-       && echo "CLASS_DIAGRAMS         = $(DOXYGEN_GRAPHICS)" \
-       && echo "DOT_MULTI_TARGETS      = YES" \
        && echo "INPUT                  = src/" \
        && echo "STRIP_FROM_PATH        = $$(pwd)/doxy/src" \
        && echo "OUTPUT_DIRECTORY       = output/" \
@@ -107,6 +100,18 @@ doxy/html/doc-version: doxy/html $(man1_HTMLS) $(man5_HTMLS)
        $(Q) test -z "$(man1_HTMLS)$(man5_HTMLS)" || { $(MKDIR_P) doxy/html/man/ && cp $(man1_HTMLS) 
$(man5_HTMLS) doxy/html/man/ ; }
        $(Q) echo "$(PACKAGE)-$(topbuildid)" > $@
 
+# == docs ==
+# Build slim (and fast) docs for 'make all' and build rich (but slow) docs for 'make docs'
+RICHDOCS_OFF = 's/\bIFRICH\b/NO/g;  s/\bIFSLIM\b/YES/g'
+RICHDOCS_ON  = 's/\bIFRICH\b/YES/g; s/\bIFSLIM\b/NO/g'
+RICHDOCS_SED ?= $(RICHDOCS_OFF)
+doxy/richdocs:
+       $(Q) $(MAKE) $(AM_MAKEFLAGS) clean
+       $(Q) $(MAKE) $(AM_MAKEFLAGS) all RICHDOCS_SED="$(RICHDOCS_ON)"
+       $(Q) touch $@
+docs: doxy/richdocs
+.PHONY: docs
+
 # == install docs/doxy/html ==
 docs_html_installbase   = $(beastdocdir)
 noinst_DATA            += doxy/html/doc-version        # AM target to trigger docs/doxy/html builds
@@ -125,7 +130,7 @@ uninstall-local: docs-html-uninstall
 
 # == upload-docs ==
 CHECK_RSYNC = { command -v rsync >/dev/null && { echo "3.0.0" ; rsync --version 2>&1 | sed 's/[^0-9]*// ; 
1q' ; } | sort -VC ; }
-upload-docs: $(noinst_DATA)                            # force docs/doxy/html builds
+upload-docs: docs                                      # force rich docs/doxy/html builds
        $(AM_V_GEN)
        $(Q) ${CHECK_RSYNC} || { echo "$@: failed to detect recent version: rsync"; exit 1; }
        rsync -zaHP --del doxy/html/ testbit:sites/beast/docs/$(docs_upload_name)
diff --git a/docs/doxygen.cfg b/docs/doxygen.cfg
index fe59b67..9fb8f93 100644
--- a/docs/doxygen.cfg
+++ b/docs/doxygen.cfg
@@ -55,7 +55,6 @@ EXPAND_AS_DEFINED       =
 
 DISABLE_INDEX          = YES
 GENERATE_HTML          = YES
-VERBATIM_HEADERS       = NO
 GENERATE_TREEVIEW      = YES
 #HTML_OUTPUT            = html
 #HTML_FILE_EXTENSION    = .html
@@ -75,18 +74,9 @@ DOT_TRANSPARENT         = YES
 DOT_FONTNAME           = "Verdana Bold"
 #DOT_FONTNAME            = "DejaVuSansMono Bold"
 DOT_FONTSIZE            = 11
-UML_LOOK               = NO
-CLASS_GRAPH            = YES
-COLLABORATION_GRAPH    = NO
-GROUP_GRAPHS           = YES
-TEMPLATE_RELATIONS     = NO
-INCLUDE_GRAPH          = NO
-INCLUDED_BY_GRAPH      = YES
-GRAPHICAL_HIERARCHY    = YES
-DIRECTORY_GRAPH                = YES
-CALL_GRAPH             = NO
-CALLER_GRAPH           = NO
-
+DOT_MULTI_TARGETS      = YES
+DOT_GRAPH_MAX_NODES    = 999
+MAX_DOT_GRAPH_DEPTH    = 1
 
 ALIASES += amp="&"
 ALIASES += note="<br><em><b>Note:</b></em>" Note="<br><em><b>Note:</b></em>" NOTE="<br><em><b>Note:</b></em>"
@@ -103,3 +93,21 @@ ALIASES +=  DISCOURAGED="\xrefitem unstable \"Unstable\" \"Unstable API\" @b DIS
 ALIASES +=   DEPRECATED="\xrefitem unstable \"Unstable\" \"Unstable API\" @b DEPRECATED"
 ALIASES +=   deprecated="\xrefitem unstable \"Unstable\" \"Unstable API\" @b DEPRECATED"
 ALIASES += EXPERIMENTAL="\xrefitem unstable \"Unstable\" \"Unstable API\" @b EXPERIMENTAL"
+
+# settings for building slim vs rich docs, see Makefile.am
+VERBATIM_HEADERS       = IFRICH
+REFERENCED_BY_RELATION = IFRICH
+CLASS_DIAGRAMS         = IFRICH
+CLASS_GRAPH            = IFRICH
+GROUP_GRAPHS           = IFRICH
+TEMPLATE_RELATIONS     = IFRICH
+INCLUDED_BY_GRAPH      = IFRICH
+GRAPHICAL_HIERARCHY    = IFRICH
+DIRECTORY_GRAPH                = IFRICH
+UML_LOOK               = IFRICH
+COLLABORATION_GRAPH    = IFRICH
+TEMPLATE_RELATIONS     = IFRICH
+INCLUDE_GRAPH          = IFRICH
+CALL_GRAPH             = IFRICH
+CALLER_GRAPH           = IFRICH
+HAVE_DOT               = IFRICH