From e6918187568dbd01842d8d1d2c808ce16a894239 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 21 Apr 2024 13:54:28 +0200 Subject: Adding upstream version 18.2.2. Signed-off-by: Daniel Baumann --- src/boost/tools/docca/util/comparison/README.md | 28 ++++++++++++++++++++++ .../docca/util/comparison/build-and-compare.sh | 24 +++++++++++++++++++ .../tools/docca/util/comparison/compare-all.sh | 27 +++++++++++++++++++++ .../tools/docca/util/comparison/grep-expressions | 4 ++++ src/boost/tools/docca/util/comparison/sed-commands | 2 ++ .../docca/util/comparison/update-all-baselines.sh | 16 +++++++++++++ .../docca/util/comparison/update-baseline-html.sh | 19 +++++++++++++++ .../docca/util/comparison/watch-all-builds.sh | 6 +++++ 8 files changed, 126 insertions(+) create mode 100644 src/boost/tools/docca/util/comparison/README.md create mode 100755 src/boost/tools/docca/util/comparison/build-and-compare.sh create mode 100755 src/boost/tools/docca/util/comparison/compare-all.sh create mode 100644 src/boost/tools/docca/util/comparison/grep-expressions create mode 100644 src/boost/tools/docca/util/comparison/sed-commands create mode 100755 src/boost/tools/docca/util/comparison/update-all-baselines.sh create mode 100755 src/boost/tools/docca/util/comparison/update-baseline-html.sh create mode 100755 src/boost/tools/docca/util/comparison/watch-all-builds.sh (limited to 'src/boost/tools/docca/util/comparison') diff --git a/src/boost/tools/docca/util/comparison/README.md b/src/boost/tools/docca/util/comparison/README.md new file mode 100644 index 000000000..0c869e0d9 --- /dev/null +++ b/src/boost/tools/docca/util/comparison/README.md @@ -0,0 +1,28 @@ +# Docca comparison scripts + +The scripts in this directory help guard against docca regressions by +comparing a previous doc build's output with the latest output +(after normalizing/scrubbing the results to eliminate non-substantive +changes). + +Probably the easiest thing to do is add this directory to your PATH +(or create an alias to the two scripts herein). + +The normal sequence goes like this: + +1. Run a baseline build from inside your project's doc directory by invoking + *update-baseline-html.sh* +2. Implement new feature or bug fix in docca (usually by updating XSLT) +3. Run a comparison build from inside your project's doc directory by invoking + *build-and-compare.sh* +4. Review the output (in diffs.txt) to make sure everything looks good and nothing broke +5. Otherwise, fix the regression and try again! + +This utility can also be useful for examining the impacts of other changes +(such as a Doxygen upgrade!). + +## Implementation details + +The file named *grep-expressions* is used to filter out all but the matching files +that need scrubbing. The resulting files are passed to sed and updated *in situ* based +on the commands in the file named *sed-commands*. diff --git a/src/boost/tools/docca/util/comparison/build-and-compare.sh b/src/boost/tools/docca/util/comparison/build-and-compare.sh new file mode 100755 index 000000000..182f5da9c --- /dev/null +++ b/src/boost/tools/docca/util/comparison/build-and-compare.sh @@ -0,0 +1,24 @@ +# This script runs a build and compares the scrubbed/normalized +# results against the scrubbed results of a previous build (run using +# update-baseline-html.sh). It is primarily used to guard against +# XSLT regressions in docca. + +SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )" + +! test -d htmlPREVIOUS_SCRUBBED && echo "First run update-baseline-html.sh" && exit + +rm -rf html_SCRUBBED + +echo "Running clean build..." +b2 clean +b2 + +echo "Scrubbing results and storing as html_SCRUBBED..." +cp -r html html_SCRUBBED +cd html_SCRUBBED +grep -rl -f ${SCRIPT_DIR}/grep-expressions . | xargs sed -i -f ${SCRIPT_DIR}/sed-commands + +echo "Showing diffs from previous build (stored in diffs.txt):" +cd .. +diff -r htmlPREVIOUS_SCRUBBED html_SCRUBBED >diffs.txt +cat diffs.txt diff --git a/src/boost/tools/docca/util/comparison/compare-all.sh b/src/boost/tools/docca/util/comparison/compare-all.sh new file mode 100755 index 000000000..1a8dbd9d9 --- /dev/null +++ b/src/boost/tools/docca/util/comparison/compare-all.sh @@ -0,0 +1,27 @@ +cd ~/boost/tools/docca/example +build-and-compare.sh 2>&1 & + +cd ~/boost/libs/static_string/doc +build-and-compare.sh 2>&1 & + +cd ~/boost/libs/url/doc +build-and-compare.sh 2>&1 & + +cd ~/boost/libs/json/doc +build-and-compare.sh 2>&1 & + +cd ~/boost/libs/beast/doc +build-and-compare.sh 2>&1 & + +wait + +echo "~/boost/tools/docca/example/diffs.txt:" +cat ~/boost/tools/docca/example/diffs.txt +echo "~/boost/libs/static_string/doc/diffs.txt:" +cat ~/boost/libs/static_string/doc/diffs.txt +echo "~/boost/libs/url/doc/diffs.txt:" +cat ~/boost/libs/url/doc/diffs.txt +echo "~/boost/libs/json/doc/diffs.txt:" +cat ~/boost/libs/json/doc/diffs.txt +echo "~/boost/libs/beast/doc/diffs.txt:" +cat ~/boost/libs/beast/doc/diffs.txt diff --git a/src/boost/tools/docca/util/comparison/grep-expressions b/src/boost/tools/docca/util/comparison/grep-expressions new file mode 100644 index 000000000..5b47be5f6 --- /dev/null +++ b/src/boost/tools/docca/util/comparison/grep-expressions @@ -0,0 +1,4 @@ +

Last revised: diff --git a/src/boost/tools/docca/util/comparison/sed-commands b/src/boost/tools/docca/util/comparison/sed-commands new file mode 100644 index 000000000..3e2da7bf3 --- /dev/null +++ b/src/boost/tools/docca/util/comparison/sed-commands @@ -0,0 +1,2 @@ +s/\(

Last revised: \)[^<]\+/\1/g diff --git a/src/boost/tools/docca/util/comparison/update-all-baselines.sh b/src/boost/tools/docca/util/comparison/update-all-baselines.sh new file mode 100755 index 000000000..23928710c --- /dev/null +++ b/src/boost/tools/docca/util/comparison/update-all-baselines.sh @@ -0,0 +1,16 @@ +cd ~/boost/tools/docca/example +update-baseline-html.sh 2>&1 & + +cd ~/boost/libs/static_string/doc +update-baseline-html.sh >build_output.txt 2>&1 & + +cd ~/boost/libs/url/doc +update-baseline-html.sh >build_output.txt 2>&1 & + +cd ~/boost/libs/json/doc +update-baseline-html.sh >build_output.txt 2>&1 & + +cd ~/boost/libs/beast/doc +update-baseline-html.sh >build_output.txt 2>&1 & + +wait diff --git a/src/boost/tools/docca/util/comparison/update-baseline-html.sh b/src/boost/tools/docca/util/comparison/update-baseline-html.sh new file mode 100755 index 000000000..8306cfc9e --- /dev/null +++ b/src/boost/tools/docca/util/comparison/update-baseline-html.sh @@ -0,0 +1,19 @@ +# This script runs a new build and moves the results so they +# can be used as a comparison baseline against subsequent builds +# that are run using build-and-compare.sh + +SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )" + +rm -rf htmlPREVIOUS htmlPREVIOUS_SCRUBBED + +echo "Running clean build..." +b2 clean +b2 + +echo "Moving results to htmlPREVIOUS..." +mv html htmlPREVIOUS + +echo "Scrubbing htmlPREVIOUS and storing as htmlPREVIOUS_SCRUBBED for use by build-and-compare.sh..." +cp -r htmlPREVIOUS htmlPREVIOUS_SCRUBBED +cd htmlPREVIOUS_SCRUBBED +grep -rl -f ${SCRIPT_DIR}/grep-expressions . | xargs sed -i -f ${SCRIPT_DIR}/sed-commands diff --git a/src/boost/tools/docca/util/comparison/watch-all-builds.sh b/src/boost/tools/docca/util/comparison/watch-all-builds.sh new file mode 100755 index 000000000..cf6f9fbcd --- /dev/null +++ b/src/boost/tools/docca/util/comparison/watch-all-builds.sh @@ -0,0 +1,6 @@ +tail -f \ +~/boost/tools/docca/example/build_output.txt \ +~/boost/libs/static_string/doc/build_output.txt \ +~/boost/libs/url/doc/build_output.txt \ +~/boost/libs/json/doc/build_output.txt \ +~/boost/libs/beast/doc/build_output.txt -- cgit v1.2.3