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>

2 files changed, 9 insertions, 4 deletions

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));