You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
289 lines
8.5 KiB
289 lines
8.5 KiB
#!/bin/bash
|
|
|
|
# This script is used to generate the TribitsUsersGuide.(html,pdf) and
|
|
# TribitsMaintainersGuide.html files. You just run it from this directory as:
|
|
#
|
|
# cd <this-dir>
|
|
# ./generate-guide.sh all
|
|
#
|
|
# To just generate the users guide, run:
|
|
#
|
|
# ./generate-guide.sh ug
|
|
#
|
|
# To just generate the maintainers guide, run:
|
|
#
|
|
# ./generate-guide.sh mg
|
|
#
|
|
# This script automatically extracts detailed TriBITS documentation from the
|
|
# *.cmake files using the tool extract_rst_cmake_doc.py (which works kind of
|
|
# like doxygen). To see output from extract_rst_cmake_doc.py just run the
|
|
# script as:
|
|
#
|
|
# $ env TRIBITS_DEV_GUIDE_EXTRACT_RST_CMAKE_DOC_EXTRA_ARGS=--do-trace \
|
|
# ./generate-guide.sh all
|
|
#
|
|
# NOTE: If you see rst2html or rst2latex errors in the files
|
|
# TribitsUsersGuide.rst or TribitsMaintainersGuide.rst with line numbers that
|
|
# don't seem to make sense, this is likely due to the include of
|
|
# TribitsDetailedMacroFunctionDoc.rst. To adjust the line numbers, subtract
|
|
# the line number of the include for TribitsDetailedMacroFunctionDoc.rst in
|
|
# TribitsUsersGuide.rst or TribitsMaintainersGuide.rst from the line number
|
|
# given in the output and that will be the line number in the file
|
|
# TribitsUsersGuide.rst or TribitsMaintainersGuide.rst. You can then match
|
|
# that up with the original text in the *.cmake file that this came from for
|
|
# the given macro or function.
|
|
#
|
|
# NOTE: To skip the extraction of the documentation from the *.cmake files,
|
|
# just sent the env TRIBITS_DEV_GUIDE_SKIP_DOCUMENTATION_EXTRACTION variable
|
|
# as:
|
|
#
|
|
# $ env TRIBITS_DEV_GUIDE_SKIP_DOCUMENTATION_EXTRACTION=1 \
|
|
# ./generate-guide.sh
|
|
#
|
|
# That will result in the generated files TribitsMacroFunctionDoc.rst and
|
|
# UtilsMacroFunctionDoc.rst being left as is. This would be useful to speed
|
|
# up builds (it is very fast) but is more useful when spell checking and
|
|
# editing the documentation. This speeds up the editing process and then the
|
|
# updated documentation can be copied back into the *.cmake files of origin.
|
|
#
|
|
# Enjoy!
|
|
#
|
|
|
|
|
|
#
|
|
# Parse command-line arguments
|
|
#
|
|
|
|
generate_maintainers_guide=0
|
|
generate_users_guide=0
|
|
skip_final_generation=0
|
|
|
|
while (( "$#" )); do
|
|
case "$1" in
|
|
mg|maintainers_guide)
|
|
generate_maintainers_guide=1
|
|
shift
|
|
;;
|
|
ug|users_guide)
|
|
generate_users_guide=1
|
|
shift
|
|
;;
|
|
all)
|
|
generate_maintainers_guide=1
|
|
generate_users_guide=1
|
|
shift
|
|
;;
|
|
--skip-final-generation)
|
|
skip_final_generation=1
|
|
shift
|
|
;;
|
|
*)
|
|
echo "Error: The argument '$1' is not supported!"
|
|
exit 1
|
|
;;
|
|
esac
|
|
done
|
|
|
|
|
|
#
|
|
# Functions
|
|
#
|
|
|
|
source ../utils/gen_doc_utils.sh
|
|
|
|
|
|
function generate_gitdist_dist_help_topic {
|
|
help_topic_name=$1
|
|
../../python_utils/gitdist --dist-help=$help_topic_name &> gitdist-dist-help-$help_topic_name.txt.tmp
|
|
update_if_different gitdist-dist-help-$help_topic_name.txt tmp
|
|
}
|
|
|
|
|
|
function tribits_extract_rst_cmake_doc {
|
|
dir=$1
|
|
extra_args=$2
|
|
|
|
cd ${dir}
|
|
echo $PWD
|
|
|
|
if [ "$TRIBITS_DEV_GUIDE_SKIP_DOCUMENTATION_EXTRACTION" == "" ] ; then
|
|
|
|
echo
|
|
echo "Extracting TriBITS documentation from *.cmake files ..."
|
|
echo
|
|
../../../python_utils/extract_rst_cmake_doc.py \
|
|
--extract-from=../../../core/package_arch/,../../../ci_support/,../../../core/utils/,../../../ctest_driver/ \
|
|
--rst-file-pairs=../TribitsMacroFunctionDocTemplate.rst:TribitsMacroFunctionDoc.rst.tmp,../UtilsMacroFunctionDocTemplate.rst:UtilsMacroFunctionDoc.rst.tmp,../TribitsSystemMacroFunctionDocTemplate.rst:TribitsSystemMacroFunctionDoc.rst.tmp \
|
|
${extra_args} \
|
|
--file-name-path-base-dir=../../.. \
|
|
$TRIBITS_DEV_GUIDE_EXTRACT_RST_CMAKE_DOC_EXTRA_ARGS
|
|
|
|
update_if_different TribitsMacroFunctionDoc.rst tmp
|
|
update_if_different UtilsMacroFunctionDoc.rst tmp
|
|
update_if_different TribitsSystemMacroFunctionDoc.rst tmp
|
|
|
|
fi
|
|
|
|
cd -
|
|
|
|
}
|
|
|
|
|
|
function tribits_extract_other_doc {
|
|
|
|
if [ "$TRIBITS_DEV_GUIDE_SKIP_OTHER_EXTRACTION" == "" ] ; then
|
|
|
|
echo
|
|
echo "Generating list of Standard TriBITS TPLs ..."
|
|
echo
|
|
ls -w 1 ../../core/std_tpls/ &> TribitsStandardTPLsList.txt.tmp
|
|
update_if_different TribitsStandardTPLsList.txt tmp
|
|
|
|
echo
|
|
echo "Generating list of Common TriBITS TPLs ..."
|
|
echo
|
|
ls -w 1 ../../common_tpls/ &> TribitsCommonTPLsList.txt.tmp
|
|
update_if_different TribitsCommonTPLsList.txt tmp
|
|
|
|
echo
|
|
echo "Generating Directory structure of TribitsHelloWorld ..."
|
|
echo
|
|
../../python_utils/tree.py -f -c -x ../../examples/TribitsHelloWorld/ \
|
|
&> TribitsHelloWorldDirAndFiles.txt.tmp
|
|
update_if_different TribitsHelloWorldDirAndFiles.txt tmp
|
|
|
|
echo
|
|
echo "Generating output for 'checkin-test.py --help' ..."
|
|
echo
|
|
../../ci_support/checkin-test.py --help &> checkin-test-help.txt.tmp
|
|
update_if_different checkin-test-help.txt tmp
|
|
|
|
echo
|
|
echo "Generating output for 'gitdist --help' and '--dist-help=<topic>' ..."
|
|
echo
|
|
../../python_utils/gitdist --help &> gitdist-help.txt.tmp
|
|
update_if_different gitdist-help.txt tmp
|
|
generate_gitdist_dist_help_topic overview
|
|
generate_gitdist_dist_help_topic repo-selection-and-setup
|
|
generate_gitdist_dist_help_topic dist-repo-status
|
|
generate_gitdist_dist_help_topic repo-versions
|
|
generate_gitdist_dist_help_topic aliases
|
|
generate_gitdist_dist_help_topic default-branch
|
|
generate_gitdist_dist_help_topic move-to-base-dir
|
|
generate_gitdist_dist_help_topic usage-tips
|
|
generate_gitdist_dist_help_topic script-dependencies
|
|
generate_gitdist_dist_help_topic all
|
|
|
|
echo
|
|
echo "Generating output for 'clone_extra_repos.py --help' ..."
|
|
echo
|
|
../../ci_support/clone_extra_repos.py --help \
|
|
&> clone_extra_repos-help.txt.tmp
|
|
update_if_different clone_extra_repos-help.txt tmp
|
|
|
|
echo
|
|
echo "Generating output for 'snapshot-dir.py --help' ..."
|
|
echo
|
|
env SNAPSHOT_DIR_DUMMY_DEFAULTS=1 ../../python_utils/snapshot-dir.py --help \
|
|
&> snapshot-dir-help.txt.tmp
|
|
update_if_different snapshot-dir-help.txt tmp
|
|
|
|
echo
|
|
echo "Generating output for 'is_checkin_tested_commit.py --help' ..."
|
|
echo
|
|
../../ci_support/is_checkin_tested_commit.py --help \
|
|
&> is_checkin_tested_commit.txt.tmp
|
|
update_if_different is_checkin_tested_commit.txt tmp
|
|
|
|
echo
|
|
echo "Generating output for 'get-tribits-packages-from-files-list.py --help' ..."
|
|
echo
|
|
../../ci_support/get-tribits-packages-from-files-list.py --help \
|
|
&> get-tribits-packages-from-files-list.txt.tmp
|
|
update_if_different get-tribits-packages-from-files-list.txt tmp
|
|
|
|
echo
|
|
echo "Generating output for 'get-tribits-packages-from-last-tests-failed.py --help' ..."
|
|
echo
|
|
../../ci_support/get-tribits-packages-from-last-tests-failed.py --help \
|
|
&> get-tribits-packages-from-last-tests-failed.txt.tmp
|
|
update_if_different get-tribits-packages-from-last-tests-failed.txt tmp
|
|
|
|
echo
|
|
echo "Generating output for 'filter-packages-list.py --help' ..."
|
|
echo
|
|
../../ci_support/filter-packages-list.py --help \
|
|
&> filter-packages-list.txt.tmp
|
|
update_if_different filter-packages-list.txt tmp
|
|
|
|
echo
|
|
echo "Generating output for 'install_devtools.py --help' ..."
|
|
echo
|
|
../../devtools_install/install_devtools.py --help \
|
|
&> install_devtools-help.txt.tmp
|
|
update_if_different install_devtools-help.txt tmp
|
|
|
|
fi
|
|
|
|
if [ -e "../../../README.DIRECTORY_CONTENTS.rst" ] ; then
|
|
echo
|
|
echo "Copy TriBITS/README.DIRECTORY_CONTENTS.rst to TriBITS.README.DIRECTORY_CONTENTS.rst ..."
|
|
echo
|
|
cp ../../../README.DIRECTORY_CONTENTS.rst TriBITS.README.DIRECTORY_CONTENTS.rst.tmp
|
|
else
|
|
echo
|
|
echo "TriBITS/README.DIRECTORY_CONTENTS.rst does not exist to copy!"
|
|
echo
|
|
touch TriBITS.README.DIRECTORY_CONTENTS.rst.tmp
|
|
fi
|
|
update_if_different TriBITS.README.DIRECTORY_CONTENTS.rst tmp
|
|
|
|
}
|
|
|
|
|
|
function make_final_doc_in_subdir {
|
|
dir_name=$1
|
|
if [[ "${skip_final_generation}" == "0" ]] ; then
|
|
cd $dir_name
|
|
echo $PWD
|
|
make
|
|
cd -
|
|
else
|
|
echo
|
|
echo "Skipping final generation of '${dir_name}' on request!"
|
|
echo
|
|
fi
|
|
}
|
|
|
|
|
|
#
|
|
# Executable code
|
|
#
|
|
|
|
generate_git_version_file
|
|
|
|
tribits_extract_other_doc
|
|
|
|
if [[ "${generate_users_guide}" == "1" ]] ; then
|
|
|
|
echo
|
|
echo "Generating HTML and PDF files for users guide ..."
|
|
echo
|
|
|
|
tribits_extract_rst_cmake_doc users_guide
|
|
|
|
make_final_doc_in_subdir users_guide
|
|
|
|
fi
|
|
|
|
if [[ "${generate_maintainers_guide}" == "1" ]] ; then
|
|
|
|
echo
|
|
echo "Generating HTML file for maintainers_guide ..."
|
|
echo
|
|
|
|
tribits_extract_rst_cmake_doc maintainers_guide --show-file-name-line-num
|
|
|
|
make_final_doc_in_subdir maintainers_guide
|
|
|
|
fi
|
|
|