Skip to content

Commit 947b99e

Browse files
expipiplus1expipiplus1
authored
Add Table of Contents check to CI, and bot script to regenerate (#5618)
* Sort filenames when generating table of contents The order of EnumerateFiles is unspecified * Add build table of contents bash script * Add toc checking to CI * Add --check-only option to toc checking * regenerate ToC
1 parent 2c82b14 commit 947b99e

File tree

4 files changed

+227
-0
lines changed

4 files changed

+227
-0
lines changed

‎.github/workflows/check-toc.yml

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
name: Check Table of Contents (comment /regenerate-toc to auto-fix)
2+
3+
on:
4+
push:
5+
branches: [master]
6+
pull_request:
7+
branches: [master]
8+
jobs:
9+
check-formatting:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v4
13+
- run: ./docs/build_toc.sh --check-only

‎.github/workflows/regenerate-toc.yml

+82
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
name: Regenerate TOC
2+
on:
3+
repository_dispatch:
4+
types: [regenerate-toc-command]
5+
jobs:
6+
regenerate-toc:
7+
runs-on: ubuntu-latest
8+
steps:
9+
- name: Checkout PR branch
10+
uses: actions/checkout@v4
11+
with:
12+
token: ${{ secrets.SLANGBOT_PAT }}
13+
repository: ${{ github.event.client_payload.pull_request.head.repo.full_name }}
14+
ref: ${{ github.event.client_payload.pull_request.head.ref }}
15+
path: pr-branch
16+
17+
- name: Checkout target branch
18+
uses: actions/checkout@v4
19+
with:
20+
token: ${{ secrets.SLANGBOT_PAT }}
21+
repository: ${{ github.event.client_payload.pull_request.base.repo.full_name }}
22+
ref: ${{ github.event.client_payload.pull_request.base.ref }}
23+
path: target-branch
24+
25+
- name: Regenerate Table of Contents
26+
id: regen
27+
run: |
28+
./target-branch/docs/build_toc.sh --source ./pr-branch
29+
30+
- name: Configure Git commit signing
31+
id: git-info
32+
run: |
33+
echo "${{ secrets.SLANGBOT_SIGNING_KEY }}" > "${{runner.temp}}"/signing_key
34+
chmod 600 "${{runner.temp}}"/signing_key
35+
git -C pr-branch config commit.gpgsign true
36+
git -C pr-branch config gpg.format ssh
37+
git -C pr-branch config user.signingkey "${{runner.temp}}"/signing_key
38+
bot_info=$(curl -s -H "Authorization: Bearer ${{ secrets.SLANGBOT_PAT }}" \
39+
"https://api.github.com/user")
40+
echo "bot_identity=$(echo $bot_info | jq --raw-output '.login + " <" + (.id|tostring) + "+" + .login + "@users.noreply.github.com>"')" >> $GITHUB_OUTPUT
41+
echo "bot_name=$(echo $bot_info | jq --raw-output '.login')" >> $GITHUB_OUTPUT
42+
43+
- name: Create Pull Request
44+
id: create-pr
45+
uses: peter-evans/create-pull-request@v7
46+
with:
47+
token: ${{ secrets.SLANGBOT_PAT }}
48+
path: pr-branch
49+
commit-message: "regenerate documentation Table of Contents"
50+
title: "Regenerate documentation ToC for PR #${{ github.event.client_payload.pull_request.number }}"
51+
body: "Automated ToC generation for ${{ github.event.client_payload.pull_request.html_url }}"
52+
committer: ${{ steps.git-info.outputs.bot_identity }}
53+
author: ${{ steps.git-info.outputs.bot_identity }}
54+
branch: regenerate-toc-${{ github.event.client_payload.pull_request.number }}-${{ github.event.client_payload.pull_request.head.ref }}
55+
base: ${{ github.event.client_payload.pull_request.head.ref }}
56+
push-to-fork: ${{ steps.git-info.outputs.bot_name }}/slang
57+
delete-branch: true
58+
59+
- name: Comment on PR
60+
uses: peter-evans/create-or-update-comment@v4
61+
if: always()
62+
with:
63+
token: ${{ secrets.SLANGBOT_PAT }}
64+
repository: ${{ github.event.client_payload.github.payload.repository.full_name }}
65+
issue-number: ${{ github.event.client_payload.pull_request.number }}
66+
body: |
67+
${{
68+
steps.regen.conclusion == 'failure'
69+
&& format('❌ Table of Contents generation failed. Please check the [workflow run](https://github.com/{0}/actions/runs/{1})', github.repository, github.run_id)
70+
|| (steps.create-pr.conclusion == 'failure'
71+
&& format('❌ Failed to create regenerate ToC pull request. Please check the [workflow run](https://github.com/{0}/actions/runs/{1})', github.repository, github.run_id)
72+
|| format('🌈 Regenerated Table of Contents, please merge the changes from [this PR]({0})', steps.create-pr.outputs.pull-request-url))
73+
}}
74+
75+
- name: Add reaction
76+
uses: peter-evans/create-or-update-comment@v4
77+
with:
78+
token: ${{ secrets.SLANGBOT_PAT }}
79+
repository: ${{ github.event.client_payload.github.payload.repository.full_name }}
80+
comment-id: ${{ github.event.client_payload.github.payload.comment.id }}
81+
reactions-edit-mode: replace
82+
reactions: hooray

‎.github/workflows/slash-command-dispatch.yml

+5
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,11 @@ jobs:
1919
"command": "format",
2020
"permission": "none",
2121
"issue_type": "pull-request"
22+
},
23+
{
24+
"command": "regenerate-toc",
25+
"permission": "none",
26+
"issue_type": "pull-request"
2227
}
2328
]
2429

‎docs/build_toc.sh

+127
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
#!/usr/bin/env bash
2+
set -e
3+
4+
script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
5+
project_root="$(dirname "$script_dir")"
6+
check_only=0
7+
8+
show_help() {
9+
me=$(basename "$0")
10+
cat <<EOF
11+
$me: Build table of contents for documentation directories
12+
13+
Usage: $me [--help] [--source <path>] [--check-only]
14+
15+
Options:
16+
--help Show this help message
17+
--source Path to project root directory (defaults to parent of the script directory)
18+
--check-only Check if TOC needs updating, exit 1 if changes needed
19+
EOF
20+
}
21+
22+
while [[ "$#" -gt 0 ]]; do
23+
case $1 in
24+
-h | --help)
25+
show_help
26+
exit 0
27+
;;
28+
--source)
29+
project_root="$2"
30+
shift
31+
;;
32+
--check-only)
33+
check_only=1
34+
;;
35+
*)
36+
echo "unrecognized argument: $1" >&2
37+
show_help >&2
38+
exit 1
39+
;;
40+
esac
41+
shift
42+
done
43+
44+
missing_bin=0
45+
46+
require_bin() {
47+
local name="$1"
48+
if ! command -v "$name" &>/dev/null; then
49+
echo "This script needs $name, but it isn't in \$PATH" >&2
50+
missing_bin=1
51+
return
52+
fi
53+
}
54+
55+
require_bin "mcs"
56+
require_bin "mono"
57+
58+
if [ "$missing_bin" -eq 1 ]; then
59+
exit 1
60+
fi
61+
62+
temp_dir=$(mktemp -d)
63+
trap 'rm -rf "$temp_dir"' EXIT
64+
65+
cd "$project_root/docs" || exit 1
66+
67+
cat >"$temp_dir/temp_program.cs" <<EOL
68+
$(cat "$script_dir/scripts/Program.cs")
69+
70+
namespace toc
71+
{
72+
class Program
73+
{
74+
static int Main(string[] args)
75+
{
76+
if (args.Length < 1)
77+
{
78+
Console.WriteLine("Please provide a directory path");
79+
return 1;
80+
}
81+
82+
try
83+
{
84+
Builder.Run(args[0]);
85+
return 0;
86+
}
87+
catch (Exception ex)
88+
{
89+
Console.WriteLine(\$"Error: {ex.Message}");
90+
return 1;
91+
}
92+
}
93+
}
94+
}
95+
EOL
96+
97+
if ! mcs -r:System.Core "$temp_dir/temp_program.cs" -out:"$temp_dir/toc-builder.exe"; then
98+
echo "Compilation of $script_dir/scripts/Program.cs failed" >&2
99+
exit 1
100+
fi
101+
102+
for dir in "user-guide" "gfx-user-guide"; do
103+
if [ -d "$script_dir/$dir" ]; then
104+
if [ "$check_only" -eq 1 ]; then
105+
# Ensure working directory is clean
106+
if ! git diff --quiet "$script_dir/$dir/toc.html" 2>/dev/null; then
107+
echo "Working directory not clean, cannot check TOC" >&2
108+
exit 1
109+
fi
110+
fi
111+
112+
if ! mono "$temp_dir/toc-builder.exe" "$script_dir/$dir"; then
113+
echo "TOC generation failed for $dir" >&2
114+
exit 1
115+
fi
116+
117+
if [ "$check_only" -eq 1 ]; then
118+
if ! git diff --quiet "$script_dir/$dir/toc.html" 2>/dev/null; then
119+
git diff --color "$script_dir/$dir/toc.html"
120+
git checkout -- "$script_dir/$dir/toc.html" 2>/dev/null
121+
exit 1
122+
fi
123+
fi
124+
else
125+
echo "Directory $dir not found" >&2
126+
fi
127+
done

0 commit comments

Comments
 (0)