From 4153544e75776e619fbb78a9e32b4499bc095bef Mon Sep 17 00:00:00 2001 From: Ellie Hermaszewska Date: Mon, 25 Nov 2024 12:23:40 +0800 Subject: [PATCH 1/4] Sort filenames when generating table of contents The order of EnumerateFiles is unspecified --- docs/scripts/Program.cs | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/scripts/Program.cs b/docs/scripts/Program.cs index d543f399ec..b256af1b28 100644 --- a/docs/scripts/Program.cs +++ b/docs/scripts/Program.cs @@ -1,7 +1,8 @@ using System; +using System.Collections.Generic; using System.IO; +using System.Linq; using System.Text; -using System.Collections.Generic; namespace toc { public class Builder @@ -128,7 +129,7 @@ public static string Run(string path) { StringBuilder outputSB = new StringBuilder(); outputSB.AppendFormat("Building table of contents from {0}...\n", path); - var files = System.IO.Directory.EnumerateFiles(path, "*.md"); + var files = System.IO.Directory.EnumerateFiles(path, "*.md").OrderBy(f => System.IO.Path.GetFileName(f)); List nodes = new List(); foreach (var f in files) { @@ -230,4 +231,4 @@ public static string Run(string path) return outputSB.ToString(); } } -} \ No newline at end of file +} From 005b4be087845a0baf72a444cf8ac8880bfd8bed Mon Sep 17 00:00:00 2001 From: Ellie Hermaszewska Date: Wed, 20 Nov 2024 20:18:05 +0800 Subject: [PATCH 2/4] Add build table of contents bash script --- docs/build_toc.sh | 107 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100755 docs/build_toc.sh diff --git a/docs/build_toc.sh b/docs/build_toc.sh new file mode 100755 index 0000000000..88343c0f62 --- /dev/null +++ b/docs/build_toc.sh @@ -0,0 +1,107 @@ +#!/usr/bin/env bash + +set -e + +script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +project_root="$(dirname "$script_dir")" + +show_help() { + me=$(basename "$0") + cat <] + +Options: + --help Show this help message + --source Path to project root directory (defaults to parent of the script directory) +EOF +} + +while [[ "$#" -gt 0 ]]; do + case $1 in + -h | --help) + show_help + exit 0 + ;; + --source) + project_root="$2" + shift + ;; + *) + echo "unrecognized argument: $1" + show_help + exit 1 + ;; + esac + shift +done + +missing_bin=0 + +require_bin() { + local name="$1" + if ! command -v "$name" &>/dev/null; then + echo "This script needs $name, but it isn't in \$PATH" >&2 + missing_bin=1 + return + fi +} + +require_bin "mcs" +require_bin "mono" + +if [ "$missing_bin" -eq 1 ]; then + exit 1 +fi + +temp_dir=$(mktemp -d) +trap 'rm -rf "$temp_dir"' EXIT + +cd "$project_root/docs" || exit 1 + +cat >"$temp_dir/temp_program.cs" < Date: Wed, 20 Nov 2024 20:18:05 +0800 Subject: [PATCH 3/4] Add toc checking to CI --- .github/workflows/check-toc.yml | 13 ++++ .github/workflows/regenerate-toc.yml | 82 ++++++++++++++++++++ .github/workflows/slash-command-dispatch.yml | 5 ++ 3 files changed, 100 insertions(+) create mode 100644 .github/workflows/check-toc.yml create mode 100644 .github/workflows/regenerate-toc.yml diff --git a/.github/workflows/check-toc.yml b/.github/workflows/check-toc.yml new file mode 100644 index 0000000000..2b478cb632 --- /dev/null +++ b/.github/workflows/check-toc.yml @@ -0,0 +1,13 @@ +name: Check Table of Contents (comment /regenerate-toc to auto-fix) + +on: + push: + branches: [master] + pull_request: + branches: [master] +jobs: + check-formatting: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - run: ./docs/build_toc.sh --check-only diff --git a/.github/workflows/regenerate-toc.yml b/.github/workflows/regenerate-toc.yml new file mode 100644 index 0000000000..973bbcf950 --- /dev/null +++ b/.github/workflows/regenerate-toc.yml @@ -0,0 +1,82 @@ +name: Regenerate TOC +on: + repository_dispatch: + types: [regenerate-toc-command] +jobs: + regenerate-toc: + runs-on: ubuntu-latest + steps: + - name: Checkout PR branch + uses: actions/checkout@v4 + with: + token: ${{ secrets.SLANGBOT_PAT }} + repository: ${{ github.event.client_payload.pull_request.head.repo.full_name }} + ref: ${{ github.event.client_payload.pull_request.head.ref }} + path: pr-branch + + - name: Checkout target branch + uses: actions/checkout@v4 + with: + token: ${{ secrets.SLANGBOT_PAT }} + repository: ${{ github.event.client_payload.pull_request.base.repo.full_name }} + ref: ${{ github.event.client_payload.pull_request.base.ref }} + path: target-branch + + - name: Regenerate Table of Contents + id: regen + run: | + ./target-branch/docs/build_toc.sh --source ./pr-branch + + - name: Configure Git commit signing + id: git-info + run: | + echo "${{ secrets.SLANGBOT_SIGNING_KEY }}" > "${{runner.temp}}"/signing_key + chmod 600 "${{runner.temp}}"/signing_key + git -C pr-branch config commit.gpgsign true + git -C pr-branch config gpg.format ssh + git -C pr-branch config user.signingkey "${{runner.temp}}"/signing_key + bot_info=$(curl -s -H "Authorization: Bearer ${{ secrets.SLANGBOT_PAT }}" \ + "https://api.github.com/user") + echo "bot_identity=$(echo $bot_info | jq --raw-output '.login + " <" + (.id|tostring) + "+" + .login + "@users.noreply.github.com>"')" >> $GITHUB_OUTPUT + echo "bot_name=$(echo $bot_info | jq --raw-output '.login')" >> $GITHUB_OUTPUT + + - name: Create Pull Request + id: create-pr + uses: peter-evans/create-pull-request@v7 + with: + token: ${{ secrets.SLANGBOT_PAT }} + path: pr-branch + commit-message: "regenerate documentation Table of Contents" + title: "Regenerate documentation ToC for PR #${{ github.event.client_payload.pull_request.number }}" + body: "Automated ToC generation for ${{ github.event.client_payload.pull_request.html_url }}" + committer: ${{ steps.git-info.outputs.bot_identity }} + author: ${{ steps.git-info.outputs.bot_identity }} + branch: regenerate-toc-${{ github.event.client_payload.pull_request.number }}-${{ github.event.client_payload.pull_request.head.ref }} + base: ${{ github.event.client_payload.pull_request.head.ref }} + push-to-fork: ${{ steps.git-info.outputs.bot_name }}/slang + delete-branch: true + + - name: Comment on PR + uses: peter-evans/create-or-update-comment@v4 + if: always() + with: + token: ${{ secrets.SLANGBOT_PAT }} + repository: ${{ github.event.client_payload.github.payload.repository.full_name }} + issue-number: ${{ github.event.client_payload.pull_request.number }} + body: | + ${{ + steps.regen.conclusion == 'failure' + && format('❌ Table of Contents generation failed. Please check the [workflow run](https://github.com/{0}/actions/runs/{1})', github.repository, github.run_id) + || (steps.create-pr.conclusion == 'failure' + && 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) + || format('🌈 Regenerated Table of Contents, please merge the changes from [this PR]({0})', steps.create-pr.outputs.pull-request-url)) + }} + + - name: Add reaction + uses: peter-evans/create-or-update-comment@v4 + with: + token: ${{ secrets.SLANGBOT_PAT }} + repository: ${{ github.event.client_payload.github.payload.repository.full_name }} + comment-id: ${{ github.event.client_payload.github.payload.comment.id }} + reactions-edit-mode: replace + reactions: hooray diff --git a/.github/workflows/slash-command-dispatch.yml b/.github/workflows/slash-command-dispatch.yml index 3d59498da4..0295e72401 100644 --- a/.github/workflows/slash-command-dispatch.yml +++ b/.github/workflows/slash-command-dispatch.yml @@ -19,6 +19,11 @@ jobs: "command": "format", "permission": "none", "issue_type": "pull-request" + }, + { + "command": "regenerate-toc", + "permission": "none", + "issue_type": "pull-request" } ] From bbc18682623282e1ba83af287d530aa2f030509a Mon Sep 17 00:00:00 2001 From: Ellie Hermaszewska Date: Wed, 20 Nov 2024 21:19:27 +0800 Subject: [PATCH 4/4] Add --check-only option to toc checking --- docs/build_toc.sh | 38 +++++++++++++++++++++++++++++--------- 1 file changed, 29 insertions(+), 9 deletions(-) diff --git a/docs/build_toc.sh b/docs/build_toc.sh index 88343c0f62..9c158d6a2c 100755 --- a/docs/build_toc.sh +++ b/docs/build_toc.sh @@ -1,20 +1,21 @@ #!/usr/bin/env bash - set -e script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" project_root="$(dirname "$script_dir")" +check_only=0 show_help() { me=$(basename "$0") cat <] +Usage: $me [--help] [--source ] [--check-only] Options: - --help Show this help message - --source Path to project root directory (defaults to parent of the script directory) + --help Show this help message + --source Path to project root directory (defaults to parent of the script directory) + --check-only Check if TOC needs updating, exit 1 if changes needed EOF } @@ -28,9 +29,12 @@ while [[ "$#" -gt 0 ]]; do project_root="$2" shift ;; + --check-only) + check_only=1 + ;; *) - echo "unrecognized argument: $1" - show_help + echo "unrecognized argument: $1" >&2 + show_help >&2 exit 1 ;; esac @@ -91,17 +95,33 @@ namespace toc EOL if ! mcs -r:System.Core "$temp_dir/temp_program.cs" -out:"$temp_dir/toc-builder.exe"; then - echo "Compilation failed" + echo "Compilation of $script_dir/scripts/Program.cs failed" >&2 exit 1 fi for dir in "user-guide" "gfx-user-guide"; do if [ -d "$script_dir/$dir" ]; then + if [ "$check_only" -eq 1 ]; then + # Ensure working directory is clean + if ! git diff --quiet "$script_dir/$dir/toc.html" 2>/dev/null; then + echo "Working directory not clean, cannot check TOC" >&2 + exit 1 + fi + fi + if ! mono "$temp_dir/toc-builder.exe" "$script_dir/$dir"; then - echo "TOC generation failed for $dir" + echo "TOC generation failed for $dir" >&2 exit 1 fi + + if [ "$check_only" -eq 1 ]; then + if ! git diff --quiet "$script_dir/$dir/toc.html" 2>/dev/null; then + git diff --color "$script_dir/$dir/toc.html" + git checkout -- "$script_dir/$dir/toc.html" 2>/dev/null + exit 1 + fi + fi else - echo "Directory $dir not found" + echo "Directory $dir not found" >&2 fi done