-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathMakefile-doc
361 lines (323 loc) · 18.4 KB
/
Makefile-doc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
#=======================================================================
#//! \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:[email protected]'>[email protected]</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 & 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:
#-----------------------------------------------------------------------