diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-21 11:54:28 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-21 11:54:28 +0000 |
commit | e6918187568dbd01842d8d1d2c808ce16a894239 (patch) | |
tree | 64f88b554b444a49f656b6c656111a145cbbaa28 /src/boost/tools/docca/util/comparison | |
parent | Initial commit. (diff) | |
download | ceph-b26c4052f3542036551aa9dec9caa4226e456195.tar.xz ceph-b26c4052f3542036551aa9dec9caa4226e456195.zip |
Adding upstream version 18.2.2.upstream/18.2.2
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'src/boost/tools/docca/util/comparison')
8 files changed, 126 insertions, 0 deletions
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 @@ +<dt id="ientry-id +<a class="indexterm" name="id +<a name="id +<td align="left"><p><small>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/\(<dt id="ientry-id\|<a class="indexterm" name="id\|<a name="id\)[0-9]\+/\1/g +s/\(<td align="left"><p><small>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 |