Fix numerous issues with integration documentation tags and the table of contents, and add a script to check for theses issues

1 files changed, 80 insertions, 0 deletions

diff --git a/test/script/check-toc b/test/script/check-toc
new file mode 100755
index 00000000..039707eb
--- /dev/null
+++ b/test/script/check-toc
@@ -0,0 +1,80 @@
+#!/bin/bash -eu
+
+# This script checks that the table of contents for the supported tools is
+# sorted, and that the table matches the files.
+
+toc_start_line="$( \
+    grep -m1 -n 'Integration Documentation.*|ale-integrations|' doc/ale.txt \
+    | sed 's/\([0-9]*\).*/\1/' \
+)"
+# shellcheck disable=SC2003
+toc_start_line="$(expr "$toc_start_line" + 1)"
+toc_section_size="$( \
+    tail -n +"$toc_start_line" doc/ale.txt \
+    | grep -m1 -n '^  [0-9]\+\.' \
+    | sed 's/\([0-9]*\).*/\1/' \
+)"
+# shellcheck disable=SC2003
+toc_end_line="$(expr "$toc_start_line" + "$toc_section_size" - 2)"
+
+toc_file="$(mktemp -t table-of-contents.XXXXXXXX)"
+heading_file="$(mktemp -t headings.XXXXXXXX)"
+unsorted_toc_file="$(mktemp -t ale.txt.XXXXXXXX)"
+sorted_toc_file="$(mktemp -t sorted-ale.txt.XXXXXXXX)"
+
+sed -n "$toc_start_line,$toc_end_line"p doc/ale.txt \
+    | sed 's/^    \( *[^.]\+\)\.\+|\(.\+\)|/\1, \2/' \
+    > "$toc_file"
+
+# Get all of the doc files in a natural sorted order.
+doc_files="$(/bin/ls -1v doc | grep ^ale- | sed 's/^/doc\//' | paste -sd ' ')"
+
+# shellcheck disable=SC2086
+grep -h 'ale-.*-options\|^[a-z].*\*ale-.*\*$' $doc_files \
+    | sed 's/^/  /' \
+    | sed 's/ALE Shell Integration/ALE sh Integration/' \
+    | sed 's/  ALE \(.*\) Integration/\L\1/' \
+    | sed 's/ *\*\(.\+\)\*$/, \1/' \
+    | sed 's/objective-c/objc/' \
+    | sed 's/c++/cpp/' \
+    > "$heading_file"
+
+exit_code=0
+in_section=0
+section_index=0
+
+while read -r; do
+    if [[ "$REPLY" =~ ^\  ]]; then
+        if ! ((in_section)); then
+            let section_index='section_index + 1'
+            in_section=1
+        fi
+    else
+        if ((in_section)); then
+            let section_index='section_index + 1'
+            in_section=0
+        fi
+    fi
+
+    echo "$section_index $REPLY" >> "$unsorted_toc_file"
+done < "$toc_file"
+
+
+sort -h "$unsorted_toc_file" | sed 's/[0-9]\+//' > "$sorted_toc_file"
+sed -i.bak 's/[0-9]\+//' "$unsorted_toc_file"
+rm -f "$unsorted_toc_file".bak
+
+echo 'Check for bad ToC sorting:'
+echo
+diff -U2 "$sorted_toc_file" "$unsorted_toc_file" || exit_code=$?
+
+echo 'Check for mismatched ToC and headings:'
+echo
+diff -U3 "$toc_file" "$heading_file" || exit_code=$?
+
+rm "$toc_file"
+rm "$heading_file"
+rm "$unsorted_toc_file"
+rm "$sorted_toc_file"
+
+exit "$exit_code"