songsenand
/
cgal
mirror of https://github.com/CGAL/cgal
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

generate_reference_manual version 1.1.1: 

* New features:
- Print short help when generate_reference_manual is called without parameters, long help when called with -h.
- Improved traces.

* Fixed bugs discovered when parsing Polyline_simplification_2:
- Check if package parameter exists.
- Fixed bug when parsing item name in a sub-namespace of CGAL::.
- Fixed case where default constructor was nor properly updated.
- Fixed bug in documentation of templated methods of a class.
- Added support of several include files for a class.
This commit is contained in:
Laurent Saboret 2009-03-23 14:46:07 +00:00
parent 8b0cf449c1
commit 89da9d7c2e
2 changed files with 110 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
Manual_tools/scripts/generate_reference_manual/copy_doxygen_latex_doc
View File

@ -38,7 +38,7 @@ my @placeholders = (
'ThisConcept \\\\\\\\',
'ThatConcept',
'\\\\ccNestedType\{TYPE\}\{some nested types\}',
'\\\\ccConstructor\{\w+\(\);\}\{default constructor\.\}',
'\\\\ccConstructor\{.*?;\}\{[Dd]efault constructor\.\}',
'\\\\ccMethod\{void foo\(\);\}\{some member functions\}',
'\\\\ccc\{[Ss]ome_\w+\}[,\.]',
'[Ss]ome(\\\\_\w+)+[,\.]',
@ -226,8 +226,9 @@ sub doxygen_latex_to_latex
# Use a canonic style to ease parsing
$buf =~ s/([\w\>]+)\s*&\s*/$1& /g; # Use a canonic style "type& variable" for references
$buf =~ s/(\w)=/$1 =/g; # Use a canonic style for default parameters
$buf =~ s/(\w)=/$1 =/g; # Use a canonic style "variable = default" for default parameters
$buf =~ s/=(\w)/= $1/g; # ""
$buf =~ s/<\s*(.*?)\s*>/<$1>/g; # Use a canonic style "type<parameters>" for template parameters
$buf =~ s/Constructor& Destructor/Constructor & Destructor/g;
$buf =~ s/\\item\[(.*?): +\]/\\item\[$1:\]/g;
@ -411,7 +412,7 @@ sub convert_comment_heading_name
}
# Flatten lists with only 1 item.
# Flatten a list if it contains only 1 item.
# Param: list in doxygen latex doc, of the form "\begin{description}...\end{description}".
# Return value: the list flattened or not.
sub flatten_one_item_list
@ -537,14 +538,14 @@ sub format_headings_ex
# Rename \ccNestedType, \ccEnum, \ccConstructor, \ccMethod, \ccVariable and \ccFunction expressions.
# Params:
# - concept/struct/class/... to document (without namespace)
# - concept/struct/class/... to document (without namespace nor template parameters)
# - type of the item to document: "class/struct/concept" or "function"
# - buffer containing a doxygen-generated latex file
# Return value: the formatted buffer
sub format_curly_brace_pairs_expressions
{
# Get parameters:
# - concept/struct/class/... to document (without namespace)
# - concept/struct/class/... to document (without namespace nor template parameters)
my $item_to_document = shift;
# - type of the item to document: "class/struct/concept" or "function"
my $item_type = shift;
@ -611,16 +612,34 @@ sub format_curly_brace_pairs_expressions
}
# Convert a list of include files to \ccInclude command(s).
# Param: list in doxygen latex doc, of the form "\begin{itemize}...\end{itemize}".
# Return value: the \ccInclude command(s) separated by new lines.
sub convert_include_file
{
my $buf = shift;
# Convert heading aand trailing
$buf =~ s/\\begin\{itemize\}\s*(.*?)\s*\\end\{itemize\}/$1/sm;
# Convert list items. The last one does not get a \n.
while ($buf =~ s/\\item\s*include\/(.*?)(\\item)/\\ccInclude\{$1\}\n$2/sm) {}
$buf =~ s/\\item\s*include\/(.*)/\\ccInclude\{$1\}/sm;
return $buf;
}
# Format a buffer containing a doxygen-generated documentation of a class/struct/concept,
# in latex, to match CGAL Reference Manual's format.
# Params:
# - class/struct/concept name (without namespace)
# - class/struct/concept name (without namespace nor template parameters)
# - buffer containing a doxygen-generated latex file
# Return value: the formatted buffer
sub format_doxygen_class_doc
{
# Get parameters:
# - class/struct/concept name (without namespace)
# - class/struct/concept name (without namespace nor template parameters)
my $className = shift;
# - buffer containing a doxygen-generated latex file
my $buf = shift;
@ -648,7 +667,8 @@ sub format_doxygen_class_doc
# Rename (for a class/struct) or delete (for a concept) the include file
# and insert \ccSeeAlso title at the end of the document.
my $is_concept = 0;
unless ($buf =~ s/^The documentation.*?include\/(.*?)\\end\{itemize\}/\n\n\\ccInclude\{$1\}\n\n\n\\ccSeeAlso\n\n\n/sm)
unless ($buf =~ s/^The documentation.*?(\\begin\{itemize\}.*?include\/.*?\\end\{itemize\})/
"\n\n" . convert_include_file($1) . "\n\n\n\\ccSeeAlso\n\n\n"/sme)
{
$is_concept = 1;
$buf =~ s/The documentation for this.*/\n\n\\ccSeeAlso\n\n\n/sm;
@ -738,7 +758,8 @@ sub format_doxygen_class_doc
my $method = $2;
# insert $template_params before $method in detailed section
$buf =~ s/\\paragraph\{\Q$method\E\}/\\paragraph\{$template_params$method\}/;
$buf =~ s/\\paragraph\{\Q$method\E\}/\\paragraph\{$template_params$method\}/
or warn "INTERNAL ERROR: cannot extract template parameters of $method";
}
}
@ -795,13 +816,13 @@ sub format_doxygen_class_doc
# Format a buffer containing a doxygen-generated documentation of
# a function, in latex, to match CGAL Reference Manual's format.
# Params:
# - function name (without namespace)
# - function name (without namespace nor template parameters)
# - buffer containing a doxygen-generated latex file
# Return value: the formatted buffer
sub format_doxygen_function_doc
{
# Get parameters:
# - function name (without namespace)
# - function name (without namespace nor template parameters)
my $functionName = shift;
# - buffer containing a doxygen-generated latex file
my $buf = shift;
@ -906,30 +927,33 @@ sub insert_manual_section
# - section's title
my $title = shift;
# Uncomment the next line to test that obsolete sections are properly *emptied*
# $doxy_buf = "";
# Uncomment the next line to test that obsolete sections are properly *emptied*
# $doxy_buf = "";
# Construct a pattern that matches any section title
my $all_titles_pattern = get_any_section_title_pattern();
# Extract $title section content from $doxy_buf
# Extract $title section content from $doxy_buf:
my $section = "";
if ($doxy_buf =~ /^\s*\Q$title\E(.*?)\s+$all_titles_pattern/sm) {
$section = $1;
$section =~ s/^\s+//s; # Remove heading & trailing spaces
$section =~ s/\s+$//s; # and extra carriage returns
#
# Special case: if one-line macro like \ccInclude
if ($title eq '\ccInclude') {
while ($doxy_buf =~ /^\s*(\Q$title\E\{.*?\})/smg) {
$section = "$section\n$1";
}
}
# General case
elsif ($doxy_buf =~ /^\s*\Q$title\E(.*?)\s+$all_titles_pattern/sm) {
$section = $1;
}
$section =~ s/^\s+//s; # Remove heading & trailing spaces
$section =~ s/\s+$//s; # and extra carriage returns.
# If $section is not empty, copy it to $cgal_buf.
# If $cgal_buf doesn't already contain $title, add it.
# If $cgal_buf doesn't already contain the %START-AUTO($title)..%END-AUTO($title) section, add it.
if ($section ne "")
{
# Special case: \ccInclude section is a one-line macro
if ($title eq '\ccInclude') {
$section = '\ccInclude' . $section;
}
# Add $warning\n%START-AUTO($title)..%END-AUTO($title) around $section
$section = "$warning\n%START-AUTO($title)\n\n" . $section . "\n\n%END-AUTO($title)";
@ -1004,7 +1028,7 @@ sub insert_manual_section
# Insert doxygen-generated documentation in CGAL Reference Manual's buffer
# Params:
# - Concept/struct/class/... to document
# - Concept/struct/class/... to document (without namespace nor template parameters)
# - buffer containing a CGAL Reference Manual template
# - buffer containing a doxygen-generated latex file reformated for CGAL
# - Insert missing %START-AUTO..%END-AUTO sections?
@ -1012,19 +1036,19 @@ sub insert_manual_section
sub merge_manuals
{
# Get parameters:
# - Concept/struct/class/... to document
# - Concept/struct/class/... to document (without namespace nor template parameters)
my $item_to_document = shift;
# - buffer containing a CGAL Reference Manual template
my $cgal_buf = shift;
# - buffer containing a doxygen-generated latex file reformated for CGAL
my $doxy_buf = shift;
# Uncomment the next lines to test that obsolete sections are properly *created*
# $cgal_buf =~ s/$warning\s%START-AUTO\(\\ccInclude\)\s*(\\ccInclude\{.*?\}\s)\s*%END-AUTO\(\\ccInclude\)\s*/$1/smg;
# $cgal_buf =~ s/$warning\s%START-AUTO\(.*?\).*?%END-AUTO\(.*?\)\s*//smg;
# Uncomment the next lines to test that automatic sections are properly *created*
# $cgal_buf =~ s/$warning\s%START-AUTO\(\\ccInclude\)\s*(\\ccInclude\{.*?\}\s)\s*%END-AUTO\(\\ccInclude\)\s*/$1/smg;
# $cgal_buf =~ s/$warning\s%START-AUTO\(.*?\).*?%END-AUTO\(.*?\)\s*//smg;
# Extract from $cgal_buf the part about $item_to_document
if ($cgal_buf =~ s/(.*)(^\s*\\begin\{ccRef.*?\s*\{$item_to_document[\s<\}].*?\\end\{ccRef.*?\}\s*)(.*)//sm)
if ($cgal_buf =~ s/(.*)(^\s*\\begin\{ccRef.*?\b$item_to_document[\s<\}].*?\\end\{ccRef.*?\}\s*)(.*)//sm)
{
my $start = $1;
my $part_to_document = $2;
@ -1055,6 +1079,10 @@ sub merge_manuals
# Insert back $part_to_document in the buffer
$cgal_buf = $start . $part_to_document . $end;
}
else
{
warn "INTERNAL ERROR: cannot insert doxygen-generated documentation in CGAL Reference Manual";
}
# Return updated CGAL buffer
return $cgal_buf;
@ -1068,10 +1096,11 @@ print <<"END_USAGE";
copy_doxygen_latex_doc extracts a documentation from a doxygen-generated latex file and inserts it in a CGAL Reference Manual's latex file.
Usage:
copy_doxygen_latex_doc [options] item_to_document doxygen_generated_documentation.tex template_manual.tex
-h, --help Print this help
-v, --verbose Verbose mode
-d, --debug Debug mode
copy_doxygen_latex_doc [options] item_to_document doxygen_generated_documentation.tex reference_manual.tex
item_to_document Concept/struct/class/... to document (without namespace nor template parameters)
-h, --help Print this help
-v, --verbose Verbose mode
-d, --debug Debug mode
See generate_reference_manual usage for details.
END_USAGE
@ -1085,7 +1114,7 @@ exit;
#######
# Variables
my $item_to_document = undef; # Concept/struct/class/... to document
my $item_to_document = undef; # Concept/struct/class/... to document (without namespace nor template parameters)
my $doxygen_generated_file = undef; # Input file
my $cgal_manual_file = undef; # Output file

68
Manual_tools/scripts/generate_reference_manual/generate_reference_manual
View File

@ -1,11 +1,31 @@
#!/bin/bash
# Goal : Generate automatically (most of) the Reference Manual of a CGAL package
# Author : Laurent Saboret, INRIA, 2005-2008
# Author : Laurent Saboret, INRIA, 2005-2009
# $Id:$
# URL:$
# ------------------------------------------
# Print usage and quit
usage ()
# Print short help and quit
# -------------------------
print_short_help ()
{
echo "\
Usage:
generate_reference_manual [options] -I /path/to/CGAL/include /path/to/package
-h, --help Print detailed help
-v, --verbose Verbose mode
-d, --debug Debug mode
"
exit 1
}
# Print long help and quit
# ------------------------
print_long_help ()
{
echo ""
@ -21,15 +41,15 @@ usage ()
}
#######
#
# Main
#######
# ----
# Turn traces on
# set -x
# Version
echo "generate_reference_manual version 1.1."
echo "generate_reference_manual version 1.1.1"
# Global variables
PACKAGE_ROOT_FOLDER="" # Package's root folder
@ -44,8 +64,8 @@ VERBOSE=0 # Verbose mode?
while [ "${1}" ]
do
case "${1}" in
-h|--help) # If usage
usage
-h|--help) # If request for help
print_long_help
;;
-f|--force) # Ignore obsolete option --force
;;
@ -60,12 +80,12 @@ do
-I|--include) # If -I
shift
if [ ! "${1}" ]; then # If no argument after -I
usage
print_short_help
fi
INCLUDE_PATH="${INCLUDE_PATH} ${1}"
;;
-*) # If unknown parameter
usage
print_short_help
;;
* ) # Else: package's root folder
PACKAGE_ROOT_FOLDER="${1}"
@ -76,7 +96,7 @@ done
# Check parameters
if [[ ! "${PACKAGE_ROOT_FOLDER}" || ! "${INCLUDE_PATH}" ]]; then
usage
print_short_help
fi
# Test if doxygen is installed
@ -101,10 +121,10 @@ if [[ $? != 0 ]]; then
fi
# Goto package's root folder
if [[ -d "${PACKAGE_ROOT_FOLDER}" ]]; then
if [[ -d "${PACKAGE_ROOT_FOLDER}" && -d "${PACKAGE_ROOT_FOLDER}/doc_tex" ]]; then
cd "${PACKAGE_ROOT_FOLDER}"
else
echo "ERROR: folder ${PACKAGE_ROOT_FOLDER} does not exist"
echo "ERROR: folder ${PACKAGE_ROOT_FOLDER}/doc_tex does not exist"
exit 1
fi
@ -147,15 +167,15 @@ do
for item in $items
do
# Extract scope of ${item} indicated in ${cgal_doc}.
# It may be either a namespace or a class name.
scope=`echo $item | perl -e 'while (<>) {if (m/\[(.*?)\]/) {print "$1\n";}}'`
item=`echo $item | perl -p -e 's/^\[.*?\]//'` # remove namespace
# Extract scope (namespace or a class name) of ${item} indicated in ${cgal_doc}.
# The scope may be surrounded by square braquets.
scope=`echo $item | perl -e 'while (<>) {if (m/\[?(.*::)/) {print "$1\n";}}'`
item=`echo $item | perl -p -e 's/.*::\]?//'` # remove namespace
# Find the file containing the doxygen-generated documentation.
# We search in CGAL namespace and in the global scope (e.g. for concepts).
doxygen_doc=""
for namespace in "$scope" "CGAL::$scope" "CGAL::" ""
for namespace in "$scope" "CGAL::$scope"
do
# Mangled item and namespace names in individual doxygen output files
item_base_file_name=`echo "${item}" | sed 's/_/__/g'`
@ -187,13 +207,19 @@ do
# Insert the doxygen-generated documentation into ${cgal_doc}
if [[ -f "${doxygen_doc}" ]]; then
if [[ $DEBUG == 0 ]]; then
echo "* ${item}"
if [[ $VERBOSE == 0 ]]; then
echo "Extract ${scope}${item} documentation"
else
doc_html=`basename ${doxygen_doc} | sed 's/\.tex/.html/'`
doc_html="doc_doxygen/html/${doc_html}"
echo "Extract ${scope}${item} documentation (see `basename ${cgal_doc}` and `pwd`/${doc_html})"
fi
else
echo copy_doxygen_latex_doc ${COPY_DOXYGEN_LATEX_DOC_ARGS} "${item}" "`pwd`/${doxygen_doc}" "`pwd`/${cgal_doc}"
echo copy_doxygen_latex_doc ${COPY_DOXYGEN_LATEX_DOC_ARGS} "${item}" "`pwd`/${doxygen_doc}" "`pwd`/${cgal_doc}"
fi
copy_doxygen_latex_doc ${COPY_DOXYGEN_LATEX_DOC_ARGS} "${item}" "${doxygen_doc}" "${cgal_doc}"
else
echo "ERROR: cannot find doxygen documentation for ${scope}${item} (documented in ${cgal_doc})"
echo "ERROR: cannot find doxygen documentation for ${scope}${item} (see `basename ${cgal_doc}`)"
fi
done
fi