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>

7 files changed, 175 insertions, 5 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"
               }
             ]
 
diff --git a/docs/command-line-slangc-reference.md b/docs/command-line-slangc-reference.md
index 36493b2f9..9f5295470 100644
--- a/docs/command-line-slangc-reference.md
+++ b/docs/command-line-slangc-reference.md
diff --git a/source/core/slang-command-options-writer.cpp b/source/core/slang-command-options-writer.cpp
index 9135998af..308cc4984 100644
--- a/source/core/slang-command-options-writer.cpp
+++ b/source/core/slang-command-options-writer.cpp
@@ -157,7 +157,7 @@ void MarkdownCommandOptionsWriter::_appendQuickLinks()
     const auto& categories = m_commandOptions->getCategories();
     const auto count = categories.getCount();
 
-    m_builder << "## Quick Links\n\n";
+    m_builder << "### Quick Links\n\n";
 
     for (Index categoryIndex = 0; categoryIndex < count; ++categoryIndex)
     {
@@ -317,7 +317,7 @@ void MarkdownCommandOptionsWriter::_appendDescriptionForCategory(Index categoryI
                       << "\"></a>\n";
         }
 
-        m_builder << "# " << category.name << "\n\n";
+        m_builder << "## " << category.name << "\n\n";
 
         // If there is a description output, making \n split paragraphs
         if (category.description.getLength() > 0)
@@ -351,7 +351,7 @@ void MarkdownCommandOptionsWriter::_appendDescriptionForCategory(Index categoryI
                               << "\"></a>\n";
                 }
 
-                m_builder << "## ";
+                m_builder << "### ";
                 StringUtil::join(names.getBuffer(), names.getCount(), toSlice(", "), m_builder);
                 m_builder << "\n";
 
diff --git a/source/core/slang-command-options.cpp b/source/core/slang-command-options.cpp
index a4bb8b552..30eaed333 100644
--- a/source/core/slang-command-options.cpp
+++ b/source/core/slang-command-options.cpp
@@ -333,7 +333,11 @@ void CommandOptions::addValuesWithAliases(const ConstArrayView<NameValue>& inVal
     List<NameValue> values;
     values.addRange(inValues.getBuffer(), inValues.getCount());
 
-    values.sort([](const NameValue& a, const NameValue& b) -> bool { return a.value < b.value; });
+    // Use stable_sort to preserve the original order for names with the same value.
+    std::stable_sort(
+        values.begin(),
+        values.end(),
+        [](const NameValue& a, const NameValue& b) -> bool { return a.value < b.value; });
 
     List<UnownedStringSlice> names;
 
@@ -346,6 +350,7 @@ void CommandOptions::addValuesWithAliases(const ConstArrayView<NameValue>& inVal
         const auto value = values[i].value;
         names.add(UnownedStringSlice(values[i++].name));
 
+        // For all names with the same value, preserve their original order (primary first)
         for (; i < count && values[i].value == value; ++i)
         {
             names.add(UnownedStringSlice(values[i].name));
diff --git a/tools/slang-capability-generator/capability-generator-main.cpp b/tools/slang-capability-generator/capability-generator-main.cpp
index e78880d76..f6202607a 100644
--- a/tools/slang-capability-generator/capability-generator-main.cpp
+++ b/tools/slang-capability-generator/capability-generator-main.cpp
@@ -1027,7 +1027,7 @@ void addHyperLink(StringBuilder& sbDoc, UnownedStringSlice suffix)
         }
         suffixReformatted.appendChar(i);
     }
-    sbDoc << "[" << suffix << "](#" << suffixReformatted << ")";
+    sbDoc << "[" << suffix << "](#" << suffixReformatted.toLower() << ")";
 }
 
 void setupDocumentationHeader(StringBuilder& sbDoc, const String& outPath)