#=======================================================================
#//! \file
#//! \section common_makefile_doc_general General file information
#//!   \author   Dirk Osswald 
#//!   \date     2006-10-16
#//!   
#//!   \par SVN file revision:
#//!     $Id: Makefile-doc 6435 2011-02-11 14:44:02Z Osswald2 $
#//!  
#//!   \par Project release:
#//!     see #PROJECT_RELEASE
#//!  
#//! \brief  
#//!   Makefile for generating doxygen documentation.
#//! 
#//!   This Makefile is meant to be included in other Makefiles, it
#//!   provides some documentation specific targets and relies on
#//!   some variables set externally (by the calling Makefile).
#//!
#//! \section common_makefile_doc_variables Makefile variables
#//!   The following variables must be set by the calling Makefile:
#//!   - INSTALL_BASE_DIR     - base directory for all projects. This must already exist
#//!                            since else "disconnected from network" is assumed.
#//!   - INSTALL_DIR          - base directory for installation of documentation
#//!   - PROJECT_NAME         - name of project, used also as file name prefix for PDFs
#//!   - PROJECT_RELEASE      - release name, e.g. "0.8.1.5"
#//!   - DOC_COMBINE_DOT_SRCS - list of source files to extract doxygen dot tags from, for combination in combined dot files
#//!   - RELEASE_FILE         - the file where the PROJECT_NAME / PROJECT_RELEASE are defined
#//!   - TAGFILES             - a list of TAGFILE=LOCATION definitions which can be used by the doxyfile
#//!
#//!   The variables DOC_DIR to DOC_INSTALL_DIR defined below \e can be
#//!   adjusted below, although there is no real need to do so. 
#//! 
#//! \section common_makefile_doc_targets Makefile targets
#//!   The following targets for generating documentation are meant to
#//!   be called by users. Other targets defined below are for internal
#//!   use only.
#//!   - \b \c doc : both \c doc_internal and \c doc_external (see below)
#//!   - \b \c doc_internal :
#//!     documentation for internal use. This includes
#//!	 comments marked with the \c \\internal doxygen tag, like e.g. the
#//!     subversion log messages for a file. (These log messages are
#//!     generated by the doc_logs target in the Makefile.)
#//!     The documentation is generated in DOC_INTERNAL_DIR.
#//!   - \b \c doc_external : documentation for external use (e.g. for customer).
#//!     This excludes comments marked with the \c \\internal doxygen tag.
#//!     The documentation is generated in DOC_EXTERNAL_DIR.
#//!   - \b \c doc_install : Install documentation overview in DOC_INSTALL_DIR,
#//!     documentation for internal use in DOC_INSTALL_INTERNAL_DIR and 
#//!     documentation for external use in DOC_INSTALL_EXTERNAL_DIR.
#//!   - \b \c doc_clean : Clean (remove) locally generated files
#//!     (Installed files and dirs are left alone)
#//!   
#//!   \remark 
#//!     The 'svn ls -R' command that is used in the rule of target \c doc_logs
#//!     to list all versioned files seems to report the files known at the time
#//!     of the last 'svn update' only. So in order to generate log files for
#//!     \b all versioned files which are present now \b YOU must manually do an
#//!     'svn update' first!
#//!
#//! \section common_makefile_doc_Links
#//!   - The online documentation for \c gnu \c make can be found at
#//!     <a href="http://www.gnu.org/software/make/manual/make.html">
#//!     http://www.gnu.org/software/make/manual/make.html</a>
#//!  
#//! \section common_makefile_doc_Copyright
#//!
#//!  Copyright (c) 2006 SCHUNK GmbH & Co. KG
#//!
#//!  <HR>
#//!  \internal
#//!
#//!    \subsection common_makefile_doc_details SVN related, detailed file specific information:
#//!      $LastChangedBy: Osswald2 $
#//!      $LastChangedDate: 2011-02-11 15:44:02 +0100 (Fr, 11 Feb 2011) $
#//!      \par SVN file revision:
#//!        $Id: Makefile-doc 6435 2011-02-11 14:44:02Z Osswald2 $
#//!
#//!  \subsection common_makefile_doc_changelog Changelog of this file:
#//!      \include Makefile-doc.log
#//!
#=======================================================================
#//! \cond ignore_me   doxygen cannot parse Makefiles, so just ignore it


########################################################################
# first some variables

export DOXYGEN = /usr/local/bin/doxygen

# Base directory where to place the generated doxygen documentation.
# This must be a relative path. It is used 
# - locally (relative to where the project, i.e. this Makefile, is checked out.
# - in install directory (relative to ${INSTALL_DIR})
DOC_DIR=./doc

# Directory for documentation for external use.
DOC_EXTERNAL_DIR=${DOC_DIR}/external

# Directory for documentation for internal use.
DOC_INTERNAL_DIR=${DOC_DIR}/internal

# File name for documentation for internal use (single pdf file).
DOC_INTERNAL_PDF=${DOC_DIR}/${PROJECT_NAME}-internal.pdf

# File name for documentation for external use (single pdf file).
DOC_EXTERNAL_PDF=${DOC_DIR}/${PROJECT_NAME}-external.pdf


# Directory for subversion logs (used only in internal documentation)
DOC_LOGS_DIR=${DOC_DIR}/internal/logs

# Directory where to install documentation for internal use.
DOC_INSTALL_INTERNAL_DIR = ${INSTALL_DIR}/${DOC_INTERNAL_DIR}

# Directory where to install documentation for external use.
DOC_INSTALL_EXTERNAL_DIR = ${INSTALL_DIR}/${DOC_EXTERNAL_DIR}

# Directory where to install index.html of generated documentation
DOC_INSTALL_DIR          = ${INSTALL_DIR}/${DOC_DIR} 

# Directory where to install doxygen tagfiles (common for all projects)
DOC_INSTALL_TAGS_DIR     = ${INSTALL_BASE_DIR}/tags

#
########################################################################

########################################################################
# now the targets

#-----------------------------------------------------------------------
# Targets for generating doxygen documentation

# Phony: all documentation (internal, external, html, pdf, index)
doc: doc_combine_dot doc_internal doc_external ${DOC_DIR}/index.html

${DOC_DIR}/index.html: ${RELEASE_FILE}
	@echo "<!DOCTYPE HTML PUBLIC '-//W3C//DTD HTML 4.01 Transitional//EN'>"                                      > $@ ;\
	echo "<!-- //! \cond ignore_me   doxygen cannot parse html files, so just ignore it -->"                    >> $@ ;\
	echo ""                                                                                                     >> $@ ;\
	echo "<html>"                                                                                               >> $@ ;\
	echo "  <head>"                                                                                             >> $@ ;\
	echo "    <title>Documentation overview for project '${PROJECT_NAME}' </title>"                             >> $@ ;\
	echo "  </head>"                                                                                            >> $@ ;\
	echo ""                                                                                                     >> $@ ;\
	echo "  <body>"                                                                                             >> $@ ;\
	echo "    <h1>Documentation overview for project '${PROJECT_NAME}' </h1>"                                   >> $@ ;\
	echo "    <h2>Release: ${PROJECT_RELEASE}, Date: ${PROJECT_DATE}</h2>"                                      >> $@ ;\
	echo ""                                                                                                     >> $@ ;\
	echo "    For this project the following documentation is available:"                                       >> $@ ;\
	echo "    <ul>"                                                                                             >> $@ ;\
	if [ -d '${DOC_DIR}/internal' ]; then \
	  echo "      <li> Documentation for internal use: <br>"                                                    >> $@ ;\
	  echo "  (including doxygen comments tagged with <code>\internal</code>, like e.g. change log messages)"   >> $@ ;\
	  echo "  <ul>"                                                                                             >> $@ ;\
	  if [ -e '${DOC_DIR}/internal/html/index.html' ]; then \
	    echo "    <li>HTML format: <a href='./internal/html/index.html'>./internal/html/index.html</a>"         >> $@ ;\
	  fi ;\
	  if [ -e '${DOC_DIR}/${PROJECT_NAME}-internal.pdf' ]; then \
	    echo "    <li>PDF format: <a href='./${PROJECT_NAME}-internal.pdf'>${PROJECT_NAME}-internal.pdf</a>"    >> $@ ;\
	  fi ;\
	  echo "  </ul>"                                                                                            >> $@ ;\
	fi ;\
	if [ -d '${DOC_DIR}/external' ]; then \
	  echo "      <li> Documentation for external use: <br>"                                                    >> $@ ;\
	  echo "  (excluding doxygen comments tagged with <code>\internal</code>, like e.g. change log messages)"   >> $@ ;\
	  echo "  <ul>"                                                                                             >> $@ ;\
	  if [ -e '${DOC_DIR}/external/html/index.html' ]; then \
	    echo "    <li>HTML format: <a href='./external/html/index.html'>./external/html/index.html</a>"         >> $@ ;\
	  fi ;\
	  if [ -e '${DOC_DIR}/${PROJECT_NAME}-external.pdf' ]; then \
	    echo "    <li>PDF format: <a href='./${PROJECT_NAME}-external.pdf'>${PROJECT_NAME}-external.pdf</a>"    >> $@ ;\
	  fi ;\
	  echo "  </ul>"                                                                                            >> $@ ;\
	fi ;\
	echo "    </ul>"                                                                                            >> $@ ;\
	echo ""                                                                                                     >> $@ ;\
	echo ""                                                                                                     >> $@ ;\
	echo "  <hr size='1'>"                                                                                      >> $@ ;\
	echo "    <table width='100%' style='background-color:#0b2c55; color:white;'>"                              >> $@ ;\
	echo "      <tr> "                                                                                          >> $@ ;\
	echo "  <th style='text-align: right;'><address><small>"                                                    >> $@ ;\
	echo "      <a href='mailto:dirk.osswald@de.schunk.com'>dirk.osswald@de.schunk.com</a>"                     >> $@ ;\
	echo "	    <a href='http://www.de.schunk.com'><img src='http://www.de.schunk.com/schunk_files/website_images/schunk_logo_top_navi_v2.gif' alt='SCHUNK GmbH &amp; Co. KG' align='middle' border='0'></a>" >> $@ ;\
	echo "    </small></address></th> "                                                                         >> $@ ;\
	echo "      </tr>"                                                                                          >> $@ ;\
	echo "    </table>"                                                                                         >> $@ ;\
	echo "  </body>"                                                                                            >> $@ ;\
	echo "</html>"                                                                                              >> $@ ;\
	echo "<!-- //! \endcond -->  "                                                                              >> $@
#

# Documentation for internal use (including comments marked with \internal, e.g. logs).
doc_internal: doc_logs doc_internal_html ${DOC_INTERNAL_PDF}

# Documentation for external use (excluding comments marked with \internal, e.g. logs).
doc_external: doc_external_html ${DOC_EXTERNAL_PDF}

# html and latex part (but not pdf) of internal documentation.
doc_internal_html: Doxyfile ${DOC_INTERNAL_DIR} 
	@echo "#====================================================================="
	@echo "# Generating documentation for internal use"		
	@echo "#====================================================================="
	if  ! which dot 2> /dev/null ; then \
		PATH=$$PATH:~/bin:/usr/local/bin ;  \
	fi ; \
	export PROJECT_NAME="$(PROJECT_NAME)"	      \
	       PROJECT_RELEASE="$(PROJECT_RELEASE)"   \
	       INTERNAL_DOCS="YES"		              \
	       OUTPUT_DIRECTORY="${DOC_INTERNAL_DIR}" \
	       EXAMPLE_PATH="${DOC_LOGS_DIR}" 	      \
	       ENABLED_SECTIONS="internal"            \
	       TAGFILES="${TAGFILES}"                 \
	       EXTRA_INPUT="${DOC_EXTRA_INPUT}"       \
	       EXTRA_EXCLUDE="${DOC_EXTRA_EXCLUDE}"    \
	       EXTRA_EXCLUDE_PATTERNS="${DOC_EXTRA_EXCLUDE_PATTERNS}" ;\
	${DOXYGEN} $<
	if [ -e "${DOC_DIR}/.htmlstuff/schunk_logo_top_navi_v2.gif" ] ; then \
	  cp -a "${DOC_DIR}/.htmlstuff/schunk_logo_top_navi_v2.gif" "${DOC_INTERNAL_DIR}/html/" ;\
	fi
	@echo "Generating $@ finished"

# html and latex part (but not pdf) of external documentation.
doc_external_html: Doxyfile ${DOC_EXTERNAL_DIR}
	@echo "#====================================================================="
	@echo "# Generating documentation for external use"		
	@echo "#====================================================================="
	if  ! which dot 2> /dev/null ; then \
		PATH=$$PATH:~/bin:/usr/local/bin ;  \
	fi ; \
	export PROJECT_NAME="$(PROJECT_NAME)"	      \
	       PROJECT_RELEASE="$(PROJECT_RELEASE)"   \
	       INTERNAL_DOCS="NO"		              \
	       OUTPUT_DIRECTORY="${DOC_EXTERNAL_DIR}" \
	       EXAMPLE_PATH="${DOC_LOGS_DIR}" 	      \
	       ENABLED_SECTIONS=""                    \
	       TAGFILES="${TAGFILES}"                 \
	       EXTRA_INPUT="${DOC_EXTRA_INPUT}"       \
	       EXTRA_EXCLUDE="${DOC_EXTRA_EXCLUDE}"    \
	       EXTRA_EXCLUDE_PATTERNS="${DOC_EXTRA_EXCLUDE_PATTERNS}" ;\
	${DOXYGEN} $<
	if [ -e "${DOC_DIR}/.htmlstuff/schunk_logo_top_navi_v2.gif" ] ; then \
	  cp -a "${DOC_DIR}/.htmlstuff/schunk_logo_top_navi_v2.gif" "${DOC_EXTERNAL_DIR}/html/" ;\
	fi
	@echo "Generating $@ finished"

# PDF version of internal documentation, generated from latex
${DOC_INTERNAL_PDF}: doc_internal_html
	cd ${DOC_INTERNAL_DIR}/latex ; ${MAKE} 
	mv ${DOC_INTERNAL_DIR}/latex/refman.pdf $@

# PDF version of external documentation, generated from latex
${DOC_EXTERNAL_PDF}: doc_external_html
	cd ${DOC_EXTERNAL_DIR}/latex ; ${MAKE} 
	mv ${DOC_EXTERNAL_DIR}/latex/refman.pdf $@


# Extract logs from svn (see also the remark in the header above).
#   This is VERY slow (up to 2 mins for MotionControl project)
#   So only remake this if necessary. As this is hard to 
#   detect we use a simple approach:
#   The recreation of the logfiles is forced only if
#   - they do not exist yet
#   - or - the revision of the current directory has changed
doc_logs: ${DOC_LOGS_DIR}
	@if [ -d ".svn" ] ; then                                          \
	  rev_cur=`svn info | grep Revision` ;					          \
	  rev_old=`cat ${DOC_LOGS_DIR}/revision` ;				          \
	  echo "current $$rev_cur old $$rev_old" ;				          \
	  if [ "$$rev_cur" != "$$rev_old" ]; then					      \
	    echo "Regenerated SVN-log files. This may take a while (up to 3 minutes)" ; \
	    for f in `svn ls -R`; do						              \
	      if [ ! -d "$$f" ]; then						              \
	        flog="${DOC_LOGS_DIR}/$$f.log" ;					      \
	        mkdir -p `dirname $$flog` ;					              \
	        echo "The SVN log messages of file \"$$f\":" > $$flog ;   \
	        svn log "$$f" >> "$$flog" ;						          \
	      fi ;								                          \
	    done ;								                          \
	    echo "$$rev_cur" > ${DOC_LOGS_DIR}/revision ;                 \
	  else	                                                          \
	    echo "Generated SVN-log files are most likely up to date" ;   \
	  fi ;                                                            \
	else                                                              \
	  echo "No SVN directory => no SVN-log files will be available" ; \
	fi

# Generate combined dot files for all user defined dot graphs 
#   The user can distribute a big dot graph (like a state machine) over several
#   \dot ... \enddot tags. the dotextract.sh script combines these graphs
#   into combined GRAPHNAME.dot files, where GRAPHNAME is the (common) name
#   of the digraphs. 
#   This rule will generate the combined dot files. The user must still include
#   the generated dot file with a \dotfile tag into the documentation.
doc_combine_dot: ${DOC_COMBINE_DOT_SRCS} 
	@if [ "$^" != "" ]; then \
	  echo "extracting dot tags from source files: " $+ ;\
	  $$HOME/bin/dotextract.sh -d ${DOC_DIR} $+ ;\
	fi

# generate png files too - for test purposes as this is normally done by doxygen
doc_combine_png: doc_combine_dot
	@for f in ${DOC_DIR}/*.dot ; do \
	  echo "creating png images from generated combined dot files " ${DOC_DIR}/*.dot ;\
	  dot -Tpng $$f -o $$f.png ; \
	done

# Generate directories if necessary.
${DOC_LOGS_DIR} ${DOC_EXTERNAL_DIR} ${DOC_INTERNAL_DIR}:
	mkdir -p "$@"

# generate ALL documentation and install
doc_install: doc doc_install_only

# Install documentation (html, pdf, index) in ${DOC_INSTALL_DIR} (will NOT create it first)
doc_install_only:
	@if [ ! -d ${INSTALL_BASE_DIR} ]; then \
	  echo "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!" ;\
	  echo "! The install directory '${INSTALL_BASE_DIR}' " ;\
	  echo "! is not available! Are we connected?" ;\
	  echo "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!" ;\
	  echo -e "\a" ;\
	  exit 1 ;\
	fi
	install -d                     ${DOC_INSTALL_INTERNAL_DIR}
	install -d                     ${DOC_INSTALL_EXTERNAL_DIR}
	install ${DOC_DIR}/index.html  ${DOC_INSTALL_DIR} 
	install ${DOC_DIR}/*.pdf       ${DOC_INSTALL_DIR} 
	cp -R ${DOC_INTERNAL_DIR}/html ${DOC_INSTALL_INTERNAL_DIR}/
	cp -R ${DOC_EXTERNAL_DIR}/html ${DOC_INSTALL_EXTERNAL_DIR}/

# does not work yet:
#doc_installdox:
#	install -d                     ${DOC_INSTALL_TAGS_DIR}
#	sh Doxyfile ; echo "gen=$$GENERATE_TAGFILE"

# Phony: clean up documentation stuff
doc_clean:
	rm -rf ${DOC_INTERNAL_DIR} ${DOC_EXTERNAL_DIR} 
	rm -rf ${DOC_INTERNAL_PDF} ${DOC_EXTERNAL_PDF}
	rm -rf ${DOC_DIR}/index.html
	rm -rf ${DOC_DIR}/*.tag
	rm -rf ${DOC_DIR}/*.dot ${DOC_DIR}/*.dot.png

# All the phony targets from the documentation section.
.PHONY: doc doc_internal doc_external doc_logs doc_combine_dot doc_combine_png doc_install doc_install_only doc_clean

%.tidy: %.html
	tidy --gnu-emacs y $< > /dev/null   || true
#
#-----------------------------------------------------------------------

#//! \endcond
########################################################################

#-----------------------------------------------------------------------
# emacs settings:
# Local Variables:
# mode: Makefile
# End:
#-----------------------------------------------------------------------
