Make Command Line Reference readthedocs compatible (#7048)

This change modifies the code that generates the Command Line Reference doc to output H2 headings in place of H1 headings, and H3 in place of existing H2, so that readthedocs will not treat the additional H1 headings as titles.

This change also regenerates the Command Line Reference doc, as the current copy in the repo appears to be quite out-of-date. The existing copy is also encoded as UTF-16LE, whereas the other docs are all UTF-8. The regenerated doc is also UTF-8, and all I did to generate that was run slangc.exe -help-style markdown -h > docs\command-line-slangc-reference.md 2>&1 after building slangc on Windows.

This change also adds GitHub actions workflows to check the contents of the doc, fail if a regenerated version needs to be checked in, and provide an option to regenerate it with a bot, all in a similar manner to User Guide TOC regeneration. The doc writer was producing different results from my local build until I changed how the writer sorts the shader stages. In the action, the order of pixel and fragment was reversed, despite the only difference from my local build being the OS.

---------

Co-authored-by: slangbot <ellieh+slangbot@nvidia.com>
Co-authored-by: slangbot <186143334+slangbot@users.noreply.github.com>

3 files changed, 165 insertions, 0 deletions

diff --git a/.github/workflows/check-cmdline-ref.yml b/.github/workflows/check-cmdline-ref.yml
new file mode 100644
index 000000000..2ae4dc011
--- /dev/null
+++ b/.github/workflows/check-cmdline-ref.yml
@@ -0,0 +1,50 @@
+name: Check Command Line Reference (comment /regenerate-cmdline-ref to auto-fix)
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  check-cmdline-ref:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: "recursive"
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libx11-dev
+
+      - name: Setup
+        uses: ./.github/actions/common-setup
+        with:
+          os: linux
+          compiler: gcc
+          platform: x86_64
+          config: release
+          build-llvm: false
+
+      - name: Build Slang
+        run: |
+          cmake --preset default --fresh \
+            -DSLANG_SLANG_LLVM_FLAVOR=DISABLE
+          cmake --workflow --preset release
+
+      - name: Generate command line reference
+        run: |
+          mkdir -p temp
+          "$bin_dir/slangc" -help-style markdown -h > temp/command-line-slangc-reference.md 2>&1
+
+      - name: Compare with existing reference
+        id: compare
+        run: |
+          if ! diff -q temp/command-line-slangc-reference.md docs/command-line-slangc-reference.md > /dev/null; then
+            echo "Command line reference is out of date. Diff:"
+            diff -u docs/command-line-slangc-reference.md temp/command-line-slangc-reference.md
+            echo "Please run 'slangc -help-style markdown -h > docs/command-line-slangc-reference.md 2>&1' or comment '/regenerate-cmdline-ref' on your PR."
+            exit 1
+          fi
diff --git a/.github/workflows/regenerate-cmdline-ref.yml b/.github/workflows/regenerate-cmdline-ref.yml
new file mode 100644
index 000000000..1a293f883
--- /dev/null
+++ b/.github/workflows/regenerate-cmdline-ref.yml
@@ -0,0 +1,110 @@
+name: Regenerate Command Line Reference
+on:
+  repository_dispatch:
+    types: [regenerate-cmdline-ref-command]
+jobs:
+  regenerate-cmdline-ref:
+    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
+          submodules: "recursive"
+
+      - 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
+          submodules: "recursive"
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libx11-dev
+
+      - name: Setup
+        uses: ./target-branch/.github/actions/common-setup
+        with:
+          os: linux
+          compiler: gcc
+          platform: x86_64
+          config: release
+          build-llvm: false
+
+      - name: Build Slang
+        id: build
+        run: |
+          cd pr-branch
+          cmake --preset default --fresh \
+            -DSLANG_SLANG_LLVM_FLAVOR=DISABLE
+          cmake --workflow --preset release
+
+      - name: Regenerate Command Line Reference
+        id: regen
+        run: |
+          cd pr-branch
+          mkdir -p docs
+          "$bin_dir/slangc" -help-style markdown -h > docs/command-line-slangc-reference.md 2>&1
+
+      - 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 command line reference"
+          title: "Regenerate command line reference for PR #${{ github.event.client_payload.pull_request.number }}"
+          body: "Automated command line reference 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-cmdline-ref-${{ 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.build.conclusion == 'failure'
+              && format('❌ Slang build failed. Please check the [workflow run](https://github.com/{0}/actions/runs/{1})', github.repository, github.run_id)
+              || (steps.regen.conclusion == 'failure' 
+                  && format('❌ Command line reference 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 command line reference pull request. Please check the [workflow run](https://github.com/{0}/actions/runs/{1})', github.repository, github.run_id)
+                      || format('🌈 Regenerated command line reference, 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 0295e7240..5d54da511 100644
--- a/.github/workflows/slash-command-dispatch.yml
+++ b/.github/workflows/slash-command-dispatch.yml
@@ -24,6 +24,11 @@ jobs:
                 "command": "regenerate-toc",
                 "permission": "none",
                 "issue_type": "pull-request"
+              },
+              {
+                "command": "regenerate-cmdline-ref",
+                "permission": "none",
+                "issue_type": "pull-request"
               }
             ]