Merge pull request #2644 from maxGimeno/Doc_add_one_column_to_overview-GF

Add a 3rd diff column to the documentation overview page.
This commit is contained in:
Laurent Rineau 2017-12-05 18:27:09 +01:00
commit 4544da8e1f
5 changed files with 180 additions and 99 deletions

View File

@ -1,7 +1,7 @@
#!/bin/bash
if [ "$1" == '--help' ]; then
echo "Usage: $0 <doc 1> [doc 2]"
exho "doc 1 and doc 2 are paths to doxygen outputs (doc_output)."
echo "doc 1 and doc 2 are paths to doxygen outputs (doc_output)."
echo "Parse the xml output of doc 1 and creates a directory with organized text files."
echo "Then, if doc_2 is specified, do the same for its xml output and make the diff between them."
exit 0

View File

@ -0,0 +1,56 @@
#!/bin/bash
if [ "$1" == '--help' ]; then
echo "Usage: $0 <doxygen 1.8.4> <doxygen 1.8.13> [publish_dir]"
echo "Compares the output of doxygen 1.8.13 and doxygen master to the one from doxygen 1.8.4, of this CGAL version, "
echo "publish_dir is the path to the dir where the testsuite results are kept"
echo "$0 must be called from doc/scripts"
exit 0
fi
mkdir -p doc_1_8_4
mkdir -p doc_1_8_13
mkdir -p doc_master
PATH_TO_1_8_4="$1"
PATH_TO_1_8_13="$2"
PUBLISH_DIR="$3"
DOXYGEN_1=$($PATH_TO_1_8_4 --version)
DOXYGEN_2=$($PATH_TO_1_8_13 --version)
#######################################
## download and build doxygen_master ##
#######################################
echo "downloading and building master"
git clone https://github.com/doxygen/doxygen.git doxygen_master 1> /dev/null
cd doxygen_master
git pull https://github.com/lrineau/doxygen.git 1> /dev/null
MASTER_DESCRIBE=$(git describe --tags)
mkdir -p build
cd build
cmake .. 1> /dev/null
make -j$NB_CORES 1> /dev/null
cd ../.. #scripts
PATH_TO_MASTER="$PWD/doxygen_master/build/bin/doxygen"
echo "done."
echo "comparing versions 1.8.4 and 1.8.13"
bash test_doxygen_versions.sh $PATH_TO_1_8_4 $PATH_TO_1_8_13 $PWD/doc_1_8_4 $PWD/doc_1_8_13 $PUBLISH_DIR
mv diff.txt diff1.txt
echo "comparing versions 1.8.4 and master"
bash test_doxygen_versions.sh $PATH_TO_1_8_4 $PATH_TO_MASTER $PWD/doc_1_8_4 $PWD/doc_master $PUBLISH_DIR
mv diff.txt diff2.txt
#update overview
CGAL_NAME=$(cat cgal_version)
python ${PWD}/testsuite.py --output-dir1 $PWD/doc_1_8_4/doc_output/ --output-dir2 $PWD/doc_1_8_13/doc_output/ --doc-log-dir $PWD/doc_1_8_4/doc_log/ \
--publish $PUBLISH_DIR --diff1 $PWD/diff1.txt --diff2 $PWD/diff2.txt --master-dir $PWD/doc_master/doc_output/ \
--cgal-version "$CGAL_NAME" --do-copy-results --version-to-keep 10 --doxygen-version1 "$DOXYGEN_1" --doxygen-version2 "$DOXYGEN_2" --master-describe "$MASTER_DESCRIBE"
#clean-up
rm -rf ./doc_1_8_4 ./doc_1_8_13 ./doc_master ./doxygen_master
rm ./diff1.txt ./diff2.txt ./cgal_version

View File

@ -2,19 +2,22 @@
set -e
if [ "$1" == '--help' ]; then
echo "Usage: $0 <doxygen_1> [doxygen_2] [publish_dir]"
echo "Usage: $0 <doxygen_1> <doxygen_2> <doc_1_dir> <doc_2_dir> <publish_dir>"
echo "Compares the output of doxygen_1 and doxygen_2 of this CGAL version, "
echo "where doxygen_1 and doxygen_2 are valid paths to doxygen executables."
echo "If doxygen_2 is not specified, the master branch of doxygen will be cloned, built and used as doxygen_2."
echo "publish_dir is the path to the dir where the testsuite results are kept"
echo "doc_##_dir is the path to the directory where the documentation will be output for the corresponding version."
echo "$0 must be called from doc/scripts"
exit 0
fi
#build reference
PATH_TO_1="$1"
PATH_TO_2="$2"
PUBLISH_DIR="$3"
PUBLISH_DIR="$5"
BUILD_DIR_1="$3"
BUILD_DIR_2="$4"
NB_CORES="$(grep -c ^processor /proc/cpuinfo)"
if [ -z $PATH_TO_1 ] || [ $(basename $PATH_TO_1) != "doxygen" ] || [ ! -e $PATH_TO_1 ]; then
@ -23,6 +26,17 @@ if [ -z $PATH_TO_1 ] || [ $(basename $PATH_TO_1) != "doxygen" ] || [ ! -e $PATH_
exit 0
fi
if [ ! -d $BUILD_DIR_1 ] || [ ! -d $BUILD_DIR_2 ] || [ ! -d $PUBLISH_DIR ]; then
echo "doc_1_dir, doc_2_dir and publish_dir must be directories."
echo "$0 --help for more information."
exit 0
fi
HAS_REF=1
TEST=$(ls $BUILD_DIR_1)
if [ -z "$TEST" ]; then
HAS_REF=0
fi
#Find the CGAL directory. If there is a directory called Documentation, this is a branch build.
#Else it is from a release.
TEMP=$PWD
@ -35,43 +49,31 @@ else
ROOT=$PWD
fi
cd $TEMP #scripts
################################################################
## Build a first time with Doxygen_1 and create the txt files ##
################################################################
if [ "$HAS_REF" -ne "1" ]; then
echo "Building reference documentation..."
mkdir -p ./build_doc
cd ./build_doc
cmake -DCGAL_DOC_RELEASE=ON -DCGAL_GENERATE_XML=ON -DDOXYGEN_EXECUTABLE="$PATH_TO_1" ../.. 1> /dev/null
make -j$NB_CORES doc &> /dev/null
echo "done."
cd ../ #scripts
echo "Creating text files for diff...."
bash -$- compare_testsuites.sh $PWD/build_doc/doc_output 1> /dev/null
mv ./doc_data ./doc_ref
echo "done."
################################################################
## Build a first time with Doxygen_1 and create the txt files ##
################################################################
#######################################
## download and build doxygen_master ##
#######################################
if [ -z $PATH_TO_2 ] || [ $(basename $PATH_TO_2) != "doxygen" ] || [ ! -e $PATH_TO_2 ]; then
echo "No second path detected. Cloning Doxygen master branch..."
git clone https://github.com/doxygen/doxygen.git doxygen_master 1> /dev/null
cd doxygen_master
git pull https://github.com/lrineau/doxygen.git 1> /dev/null
MASTER_DESCRIBE=$(git describe --tags)
mkdir -p build
cd build
cmake .. 1> /dev/null
make -j$NB_CORES 1> /dev/null
cd ../.. #scripts
PATH_TO_2="$PWD/doxygen_master/build/bin/doxygen"
echo "Building reference documentation..."
mkdir -p ./build_doc
cd ./build_doc
cmake -DCGAL_DOC_RELEASE=ON -DCGAL_GENERATE_XML=ON -DDOXYGEN_EXECUTABLE="$PATH_TO_1" ../.. 1> /dev/null
make -j$NB_CORES doc &> /dev/null
echo "done."
cd ../ #scripts
echo "Creating text files for diff...."
bash -$- compare_testsuites.sh $PWD/build_doc/doc_output 1> /dev/null
mv ./doc_data ./doc_ref
cp -r doc_ref first_doc_ref
echo "done."
mv ./build_doc ./doc_dir
else
echo "There is already a reference. Not re-building."
fi
mv ./build_doc ./doc_dir
##################################################################
## build doc with doxygen master, create the txt files and diff ##
## build doc with Doxygen_2, create the txt files and diff ##
##################################################################
echo "Building second documentation..."
mkdir -p build_doc
@ -83,7 +85,11 @@ cd ../ #scripts
DOXYGEN_1=$($PATH_TO_1 --version)
DOXYGEN_2=$($PATH_TO_2 --version)
echo "Comparing results..."
bash -$- ./compare_testsuites.sh $PWD/build_doc/doc_output $PWD/doc_ref 1> /dev/null
if [ "$HAS_REF" -eq "1" ]; then
bash -$- ./compare_testsuites.sh $PWD/build_doc/doc_output $PWD/first_doc_ref 1> /dev/null
else
bash -$- ./compare_testsuites.sh $PWD/build_doc/doc_output $PWD/doc_ref 1> /dev/null
fi
echo "done."
#add post-processing
cd ./build_doc
@ -91,48 +97,42 @@ echo "Adding postprocessing..."
make -j$NB_CORES doc_with_postprocessing &> /dev/null
echo "done."
cd .. #scripts
mv ./build_doc ./doc_master
mv ./build_doc/* $BUILD_DIR_2
#######################################################################################################################
## rebuild doc with Doxygen_1 to get the right doc_tags without GENERATE_XML because it ignores the EXCLUDE_SYMBOLS, ##
## which disrupts the logs ##
#######################################################################################################################
rm -rf ./doc_dir
mkdir ./doc_dir
cd ./doc_dir
cmake -DCGAL_DOC_RELEASE=ON -DCGAL_DOC_CREATE_LOGS="true" -DDOXYGEN_EXECUTABLE="$PATH_TO_1" ../.. 1> /dev/null
echo "Building reference documentation with postprocessing..."
make -j$NB_CORES doc &> /dev/null
make -j$NB_CORES doc &> /dev/null
make -j$NB_CORES doc_with_postprocessing &> /dev/null
echo "done."
cd .. #scripts
#get VERSION's content
if [ $IS_RELEASE = 0 ]; then
cd $ROOT
mkdir -p ./build && cd ./build
cmake .. 1> /dev/null
CGAL_NAME="$(cat $PWD/VERSION)"
cd $ROOT
rm -rf ./build
cd $ROOT/Documentation/doc/scripts
if [ "$HAS_REF" -ne "1" ]; then
#######################################################################################################################
## rebuild doc with Doxygen_1 to get the right doc_tags without GENERATE_XML because it ignores the EXCLUDE_SYMBOLS, ##
## which disrupts the logs ##
#######################################################################################################################
rm -rf ./doc_dir
cd $BUILD_DIR_1
cmake -DCGAL_DOC_RELEASE=ON -DCGAL_DOC_CREATE_LOGS="true" -DDOXYGEN_EXECUTABLE="$PATH_TO_1" ../.. 1> /dev/null
echo "Building reference documentation with postprocessing..."
make -j$NB_CORES doc &> /dev/null
make -j$NB_CORES doc &> /dev/null
make -j$NB_CORES doc_with_postprocessing &> /dev/null
echo "done."
cd .. #scripts
#get VERSION's content
if [ $IS_RELEASE = 0 ]; then
cd $ROOT
mkdir -p ./build && cd ./build
cmake -DWITH_CGAL_Core=false -DWITH_CGAL_ImageIO=false -DWITH_CGAL_Qt5=false .. 1> /dev/null
CGAL_NAME="$(cat $PWD/VERSION)"
cd $ROOT
rm -rf ./build
cd $ROOT/Documentation/doc/scripts
else
CGAL_NAME="$(cat $ROOT/VERSION)"
fi
echo "$CGAL_NAME">cgal_version
else
CGAL_NAME="$(cat $ROOT/VERSION)"
echo "There is already a reference. Not re-building."
rm -rf ./first_doc_ref
fi
#update overview
python ${PWD}/testsuite.py --output-dir $PWD/doc_dir/doc_output/ --doc-log-dir $PWD/doc_dir/doc_log/ \
--publish $PUBLISH_DIR --diff $PWD/diff.txt --master-dir $PWD/doc_master/doc_output/ \
--cgal-version "$CGAL_NAME" --do-copy-results --version-to-keep 10 --doxygen-version "$DOXYGEN_1" --master-describe "$MASTER_DESCRIBE"
echo "cleaning up"
#clean-up
rm -rf ./build_doc
rm -rf ./doc_dir
rm -rf ./doc_master
rm -rf ./doc_ref
rm -rf ./doc_data
if [ -z $PATH_TO_2 ]; then
rm -rf ./doxygen_master
fi

View File

@ -88,14 +88,18 @@ body {color: black; background-color: #C0C0D0; font-family: sans-serif;}
if args.publish and args.do_copy_results:
suffix=''
if args.doxygen_version:
suffix = ""+args.doxygen_version
link="<a href=\"output/Manual/index.html\">Documentation built</a> with <a href=\"https://github.com/CGAL/doxygen\">our fork of Doxygen {_suffix}</a>\n".format(_suffix=suffix)
if args.doxygen_version1:
suffix = ""+args.doxygen_version1
link1="<a href=\"output1/Manual/index.html\">Documentation built</a> with <a href=\"https://github.com/CGAL/doxygen\">our fork of Doxygen {_suffix}</a>\n".format(_suffix=suffix)
suffix = ''
if args.doxygen_version2:
suffix = args.doxygen_version2
link2="\n<br><a href=\"output2/Manual/index.html\">Documentation built</a> with <a href=\"https://github.com/CGAL/doxygen\">our fork of Doxygen {_suffix}</a>\n".format(_suffix=suffix)
suffix = ''
if args.master_describe:
suffix=args.master_describe
link_master="\n<br><a href=\"master/Manual/index.html\">Documentation built</a> with <a href=\"https://github.com/doxygen/doxygen\">the master version of Doxygen {_suffix}</a> (buggy), so that we see progress/regression of doxygen development as far as CGAL is concerned.\n".format(_suffix=suffix)
d = pq(page_header+link+" "+link_master+page_footer)
d = pq(page_header+link1+" "+link2+" "+link_master+page_footer)
else:
d = pq(page_header+page_footer)
logs=sorted(glob.glob('./*.log'))
@ -126,12 +130,15 @@ def main():
parser.add_argument('--publish', metavar='/path/to/publish', help='Specify this argument if the results should be published.')
parser.add_argument('--doc-log-dir', default='.', metavar='/path/to/cgal/build/dir/doc_log', help='The path of the documentation logs.')
parser.add_argument('--master-dir', default='.', metavar='/path/to/cgal/build/master_dir/doc_output', help='The path to the master build documentation.')
parser.add_argument('--output-dir', default='.', metavar='/path/to/cgal/build/dir/doc_output', help='The path to the build documentation')
parser.add_argument('--diff', metavar='/path/to/diff', help='The path to the diff file.')
parser.add_argument('--output-dir1', default='.', metavar='/path/to/cgal/build/dir1/doc_output', help='The path to the first built documentation')
parser.add_argument('--output-dir2', default='.', metavar='/path/to/cgal/build/dir2/doc_output', help='The path to the second built documentation')
parser.add_argument('--diff1', metavar='/path/to/diff', help='The path to the first diff file.')
parser.add_argument('--diff2', metavar='/path/to/diff', help='The path to the first diff file.')
parser.add_argument('--cgal-version', help='Path to a version.h file from the current release. If not specified use git hash instead.')
parser.add_argument('--version-to-keep', help='indicates the number of release testsuites that should be kept at the publishing location.')
parser.add_argument('--do-copy-results', action="store_true", help='Specify this argument if you want to copy the generated documentation into the publishing location.')
parser.add_argument('--doxygen-version', default ='', help='Specify this argument if you want to add a version number to the name of the link to the documentation.')
parser.add_argument('--doxygen-version1', default ='', help='Specify this argument if you want to add a version number to the name of the link to the first documentation.')
parser.add_argument('--doxygen-version2', default ='', help='Specify this argument if you want to add a version number to the name of the link to the second documentation.')
parser.add_argument('--master-describe', default ='', help='Specify this argument if you want to add a suffix to the name of the link to the doxygen master documentation.')
args = parser.parse_args()
@ -151,12 +158,18 @@ def main():
write_out_html(d, './index.html')
# does the diff exist ?
diff='n/a'
if args.diff:
diff_file=args.diff
if not os.path.isfile(diff_file):
sys.stderr.write('Diff file ' + diff_file + ' is not a file. Cannot diff.\n')
diff1='n/a'
if args.diff1:
diff_file1=args.diff1
if not os.path.isfile(diff_file1):
sys.stderr.write('Diff file ' + diff_file1 + ' is not a file. Cannot diff.\n')
sys.exit(1)
diff2='n/a'
if args.diff2:
diff_file2=args.diff2
if not os.path.isfile(diff_file2):
sys.stderr.write('Diff file ' + diff_file2 + ' is not a file. Cannot diff.\n')
sys.exit(1)
if args.publish:
if args.publish.endswith('/'):
publish_dir=args.publish
@ -188,24 +201,33 @@ body {color: black; background-color: #C0C0D0; font-family: sans-serif;}
<html><head><title>Manual Testsuite Overview</title></head>
<body><h1>Overviewpage of the Doxygen Manual Testsuite</h1>
<table border="1" cellspacing="2" cellpadding="5" id="revisions" class="rev-table">
<tr><th>Revision</th><th>Date</th><th>Warnings</th><th>Errors</th><th>Diff with doxygen master</th></tr></table></body>''')
<tr><th>Revision</th><th>Date</th><th>Warnings</th><th>Errors</th><th>Diff with doxygen master</th><th>Diff with doxygen 1.8.13</th></tr></table></body>''')
args_list=''
for arg in sys.argv[0:]:
args_list+=arg+' '
signature='<p id="suffix"> Generated with the command line <br /> <code> python {script_args} <br /> by {user_name}@{host_name} at {date_time} </code></p></html>'.format(
user_name=getpass.getuser(), host_name=socket.gethostname(), date_time=time.ctime(), script_args=args_list)
f.write(signature)
with open(diff_file, 'r') as myfile:
diff=myfile.read()
if not diff:
diff='none'
with open(diff_file1, 'r') as myfile:
diff1=myfile.read()
if not diff1:
diff1='none'
else:
diff='<a href="{log_path}/diff.txt">Diff between {test_version} and {master_version}.</a>'.format(
log_path=version_string, test_version=args.doxygen_version, master_version=args.master_describe)
diff1='<a href="{log_path}/diff1.txt">Diff between {test_version} and {master_version}.</a>'.format(
log_path=version_string, test_version=args.doxygen_version1, master_version=args.doxygen_version2)
with open(diff_file2, 'r') as myfile:
diff2=myfile.read()
if not diff2:
diff2='none'
else:
diff2='<a href="{log_path}/diff2.txt">Diff between {test_version} and {master_version}.</a>'.format(
log_path=version_string, test_version=args.doxygen_version1, master_version=args.master_describe)
d=pq(filename=publish_dir + 'index.html',parser="html")
revs=d('#revisions tr')
new_row='<tr><td><a href="{revision}/index.html">{revision}</a></td><td>{date}</td><td>{warnings}</td><td>{errors}</td><td>{diffs}</td></tr>'.format(
revision=version_string, date=version_date, warnings=sum[0], errors=sum[1], diffs=diff)
new_row='<tr><td><a href="{revision}/index.html">{revision}</a></td><td>{date}</td><td>{warnings}</td><td>{errors}</td><td>{diffs1}</td><td>{diffs2}</td></tr>'.format(
revision=version_string, date=version_date, warnings=sum[0], errors=sum[1], diffs1=diff2, diffs2=diff1)
revs.eq(0).after(new_row)
if args.version_to_keep:
nb_items=len(revs)
@ -231,12 +253,15 @@ body {color: black; background-color: #C0C0D0; font-family: sans-serif;}
#copy log files
shutil.copytree('.', log_target)
#copy diff
shutil.copyfile(diff_file, log_target+'/diff.txt')
shutil.copyfile(diff_file1, log_target+'/diff1.txt')
shutil.copyfile(diff_file2, log_target+'/diff2.txt')
try:
#copy documentation
if args.do_copy_results:
tgt=os.path.join(log_target, 'output')
shutil.copytree(args.output_dir, tgt, symlinks=True)
tgt=os.path.join(log_target, 'output1')
shutil.copytree(args.output_dir1, tgt, symlinks=True)
tgt=os.path.join(log_target, 'output2')
shutil.copytree(args.output_dir2, tgt, symlinks=True)
os.symlink("../MathJax", os.path.join(log_target, 'MathJax'))
except:
sys.stderr.write("Error while copying documentation\n")

View File

@ -63,7 +63,7 @@ export PYTHONPATH
PATH=/home/cgal-testsuite/local/bin:$PATH
export PATH
cd "$PWD/doc/scripts"
bash -$- ./test_doxygen_versions.sh /home/cgal-testsuite/local/bin/doxygen '' /srv/CGAL/www/Members/Manual_doxygen_test
bash -$- ./process_doc.sh /home/cgal-testsuite/local/bin/doxygen /home/mgimeno/bin/doxygen /srv/CGAL/www/Members/Manual_doxygen_test
case "$CGAL_RELEASE_ID" in
*-I-*) rsync -a --delete "/srv/CGAL/www/Members/Manual_doxygen_test/${CGAL_RELEASE_ID}/output/" /srv/CGAL/www/doc/master/
;;