mirror of https://github.com/CGAL/cgal
187 lines
7.1 KiB
Bash
Executable File
187 lines
7.1 KiB
Bash
Executable File
#!/bin/bash
|
|
|
|
# Goal : Generate automatically (most of) the Reference Manual of a CGAL package
|
|
# Author : Laurent Saboret, INRIA, 09/2005
|
|
# ----------------------------------------
|
|
|
|
# Usage
|
|
# ------
|
|
usage ()
|
|
{
|
|
echo "\
|
|
|
|
generate_reference_manual automatically generates (most of) the Reference Manual of a CGAL package. It runs doxygen to generate a Latex documentation from C++ source code, then converts it to CGAL Manual format.
|
|
If the C++ source code is commented, this tool generates the whole Reference Manual of the package (except the introduction page). If not, it generates a raw latex documentation that you will have to complete manually.
|
|
|
|
Note that this tool adds or updates automatic documentation and does *not* remove the documentation manually written. Tags %START-AUTO and %END-AUTO clearly deliminate the automatic documentation.
|
|
|
|
Usage:
|
|
generate_reference_manual [options] /path/to/package/root
|
|
-h, --help Print this help
|
|
-f, --force Insert missing %START-AUTO..%END-AUTO sections
|
|
|
|
Typical scenario:
|
|
1) Create the package's Reference Manual as described in CGAL Developer Manual.
|
|
2) Run generate_reference_manual --force to create the %START-AUTO..%END-AUTO sections.
|
|
3) Run cgal_manual.
|
|
4) Look at the generated documentation in the Reference Manual .tex files and in the PS/PDF/HTML final Reference manual. In order to complete it, you may:
|
|
a) Comment the C++ source code using doxygen conventions.
|
|
b) Write extra documentation in .tex files outside of automatic sections.
|
|
c) Modify automatic sections (make sure to delete the %START-AUTO and %END-AUTO tags).
|
|
5) Run generate_reference_manual. Do not use the --force option anymore if you modified automatic sections.
|
|
6) Goto point 3) until the Reference Manual is complete.
|
|
|
|
Tips:
|
|
* To generate a concept's documentation, you may create a fake C++ class named after the concept anywhere in the package's folders tree (use the dont_submit file to ignore it in CGAL releases).
|
|
* A comment starting by 'Concept:' will be converted to a \ccIsModel paragraph.
|
|
* A comment starting by 'Sub-concept:' will be converted to a \ccRefines paragraph.
|
|
* A comment starting by 'Models:' will be converted to a \ccHasModels paragraph.
|
|
* A comment starting by 'Design pattern:' will be converted to a \ccHeading{Design Pattern} paragraph.
|
|
* A comment starting by 'Template parameters:' will be converted to \ccParameters paragraph.
|
|
* \"Words surrounded by double quotes\" will be emphasized.
|
|
|
|
Known bugs:
|
|
* This tool has been tested with doxygen 1.4.4. It is likely that it will *not* work with other versions of doxygen.
|
|
* So far, this tool documents only concepts, classes, structs and functions.
|
|
|
|
Contact:
|
|
Please contact Laurent Saboret <Laurent.Saboret@sophia.inria.fr> if you discover a bug or wish to request for an enhancement."
|
|
exit 1
|
|
}
|
|
|
|
|
|
#######
|
|
# Main
|
|
#######
|
|
|
|
# Version
|
|
echo "generate_reference_manual version 0.7.4.";
|
|
|
|
# Global variables
|
|
ROOT_FOLDER="" # Package's root folder
|
|
COPY_DOXYGEN_LATEX_DOC_ARGS="" # Parameters for copy_doxygen_latex_doc
|
|
PACKAGE="" # Package name (without path)
|
|
DOXYFILE="" # doxygen configuration file
|
|
|
|
# Decode parameters
|
|
if [ ! "$1" ] # If no argument
|
|
then
|
|
usage
|
|
fi
|
|
while [ "$1" ]
|
|
do
|
|
case "$1" in
|
|
-h|--help) # If usage
|
|
usage
|
|
;;
|
|
-f|--force) # If --force
|
|
COPY_DOXYGEN_LATEX_DOC_ARGS="$COPY_DOXYGEN_LATEX_DOC_ARGS $1"
|
|
;;
|
|
-*) # If unknown parameter
|
|
usage
|
|
;;
|
|
* ) # Package's root folder
|
|
ROOT_FOLDER="$1"
|
|
;;
|
|
esac
|
|
shift
|
|
done
|
|
|
|
# Test if doxygen is installed
|
|
which doxygen >/dev/null 2>&1
|
|
if [[ $? != 0 ]]; then
|
|
echo "Error: cannot find doxygen"
|
|
exit 1
|
|
fi
|
|
|
|
# Test if doxygen configuration file generate_reference_manual_Doxyfile is present
|
|
DOXYFILE="$0_Doxyfile"
|
|
if [[ ! (-f "${DOXYFILE}") ]]; then
|
|
echo "Error: file ${DOXYFILE} does not exist"
|
|
exit 1
|
|
fi
|
|
|
|
# Test if copy_doxygen_latex_doc is installed
|
|
which copy_doxygen_latex_doc >/dev/null 2>&1
|
|
if [[ $? != 0 ]]; then
|
|
echo "Error: cannot find copy_doxygen_latex_doc"
|
|
exit 1
|
|
fi
|
|
|
|
# Goto package's root folder
|
|
if [[ -d "${ROOT_FOLDER}" ]]; then
|
|
cd "${ROOT_FOLDER}"
|
|
else
|
|
echo "Error: folder ${ROOT_FOLDER} does not exist"
|
|
exit 1
|
|
fi
|
|
|
|
# Remove trailing slash
|
|
ROOT_FOLDER=`pwd`
|
|
|
|
# Get package path
|
|
PACKAGE=`pwd | sed 's/.*\///'`
|
|
|
|
# Delete the output of previous uses of generate_reference_manual
|
|
rm -rf doc_doxygen
|
|
mkdir doc_doxygen
|
|
|
|
# Run doxygen
|
|
echo ""
|
|
echo "Run doxygen..."
|
|
doxygen "${DOXYFILE}" 2>&1 | grep -v "BoundingBox not found"
|
|
|
|
# Turn traces on
|
|
#set -x
|
|
|
|
# Update the Reference Manual
|
|
echo ""
|
|
echo "Update the Reference Manual:"
|
|
for manual_file in doc_tex/${PACKAGE}_ref/*.tex
|
|
do
|
|
# Skip main.tex and intro.tex
|
|
if [[ (`basename "${manual_file}"` != "main.tex") && \
|
|
(`basename "${manual_file}"` != "intro.tex") ]];
|
|
then
|
|
# Get the list of classes/structs/functions documented in "${manual_file}"
|
|
items=`egrep '^\s*\\\\begin\{ccRef' "${manual_file}" | \
|
|
perl -p -e 's/^\s*\\\\begin\{ccRef.*?\s*\{// ; s/[\s<}].*//'`
|
|
|
|
for item in $items
|
|
do
|
|
# Find the file containing the doxygen-generated documentation
|
|
#
|
|
doxygen_output_file_root=`echo "${item}" | sed 's/_/__/g'`
|
|
#
|
|
# Test if ${item} is a concept or a class in the global scope
|
|
doxygen_output_file="doc_doxygen/latex/class${doxygen_output_file_root}.tex"
|
|
# Test if ${item} is a struct in the global scope
|
|
[ ! -f "${doxygen_output_file}" ] && \
|
|
doxygen_output_file="doc_doxygen/latex/struct${doxygen_output_file_root}.tex"
|
|
# # Test if ${item} is a class in the CGAL namespace
|
|
# [ ! -f "${doxygen_output_file}" ] && \
|
|
# doxygen_output_file="doc_doxygen/latex/classCGAL_1_1${doxygen_output_file_root}.tex"
|
|
# # Test if ${item} is a struct in the CGAL namespace
|
|
# [ ! -f "${doxygen_output_file}" ] && \
|
|
# doxygen_output_file="doc_doxygen/latex/structCGAL_1_1${doxygen_output_file_root}.tex"
|
|
# Test if ${item} is a global function (in any scope)
|
|
[ ! -f "${doxygen_output_file}" ] && \
|
|
doxygen_output_file="doc_doxygen/latex/${doxygen_output_file_root}_8h.tex"
|
|
[ ! -f "${doxygen_output_file}" ] && \
|
|
doxygen_output_file=`grep -l '\\\\index{'${item} doc_doxygen/latex/*_8h.tex`
|
|
|
|
# Insert the doxygen-generated documentation into ${manual_file}
|
|
if [[ -f "${doxygen_output_file}" ]];
|
|
then
|
|
echo "${item} (${manual_file})"
|
|
#echo copy_doxygen_latex_doc $COPY_DOXYGEN_LATEX_DOC_ARGS "${item}" "`pwd`/${doxygen_output_file}" "`pwd`/${manual_file}"
|
|
copy_doxygen_latex_doc $COPY_DOXYGEN_LATEX_DOC_ARGS "${item}" "${doxygen_output_file}" "${manual_file}"
|
|
else
|
|
echo "Warning: cannot find doxygen documentation for ${item} (${manual_file})"
|
|
fi
|
|
done
|
|
fi
|
|
done
|
|
|
|
exit 0
|