[clang] [llvm] [clang-format] Add CI check confirming ClangFormatStyleOptions.rst is up-to-date. (PR #111513)

[Iuri Chaer via cfe-commits]

https://github.com/ichaer created https://github.com/llvm/llvm-project/pull/111513

* Create a new `clang-format-style-options` build target which re-generates ClangFormatStyleOptions.rst from its source header files.
* Add CI check confirming that the repository's ClangFormatStyleOptions.rst is up-to-date, so that it doesn't have to be done by reviewers.

As discussed in https://github.com/llvm/llvm-project/pull/96804#discussion_r1718407404

>From 7db80ba448fe4f434362de505330f504b9362844 Mon Sep 17 00:00:00 2001
From: Iuri Chaer <ichaer at splunk.com>
Date: Tue, 8 Oct 2024 10:52:13 +0100
Subject: [PATCH 1/2] [clang-format] Add CI check confirming
 ClangFormatStyleOptions.rst is up-to-date.

As discussed in https://github.com/llvm/llvm-project/pull/96804#discussion_r1718407404
---
 .github/workflows/docs.yml | 12 ++++++++++++
 clang/docs/CMakeLists.txt  |  6 ++++++
 2 files changed, 18 insertions(+)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 800e9291573533..25eff4dcabc4a2 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -75,6 +75,9 @@ jobs:
               - 'clang/include/clang/Basic/AttrDocs.td'
               - 'clang/include/clang/Driver/ClangOptionDocs.td'
               - 'clang/include/clang/Basic/DiagnosticDocs.td'
+            clang-format_style-headers:
+              - 'clang/include/clang/Format/Format.h'
+              - 'clang/include/clang/Tooling/Inclusions/IncludeStyle.h'
             clang-tools-extra:
               - 'clang-tools-extra/docs/**'
             lldb:
@@ -122,6 +125,15 @@ jobs:
         run: |
           cmake -B clang-build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS="clang" -DLLVM_ENABLE_SPHINX=ON ./llvm
           TZ=UTC ninja -C clang-build docs-clang-html docs-clang-man
+      - name: Confirm ClangFormatStyleOptions.rst is up-to-date
+        if: steps.docs-changed-subprojects.outputs.clang-format_style-headers_any_changed == 'true'
+        run: |
+          cmake -B clang-build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS="clang" -DLLVM_ENABLE_SPHINX=ON ./llvm
+          TZ=UTC ninja -C clang-build clang-format-style-options
+          GIT_STATUS="$(git status --porcelain=v1 clang/docs/ClangFormatStyleOptions.rst)"
+          if [ ! -z "${GIT_STATUS}" ]; then
+            echo "Error: you must build the 'clang-format-style-options' target and commit any changes to 'clang/docs/ClangFormatStyleOptions.rst'"
+          fi
       - name: Build clang-tools-extra docs
         if: steps.docs-changed-subprojects.outputs.clang-tools-extra_any_changed == 'true'
         run: |
diff --git a/clang/docs/CMakeLists.txt b/clang/docs/CMakeLists.txt
index 51e9db29f887f3..cdc65e4455f87b 100644
--- a/clang/docs/CMakeLists.txt
+++ b/clang/docs/CMakeLists.txt
@@ -1,3 +1,9 @@
+add_custom_target(clang-format-style-options
+    COMMAND "${Python3_EXECUTABLE}" dump_format_style.py
+    WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/tools"
+    DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/../include/clang/Format/Format.h"
+            "${CMAKE_CURRENT_SOURCE_DIR}/../include/clang/Tooling/Inclusions/IncludeStyle.h")
+add_dependencies(clang-format clang-format-style-options)
 
 if (DOXYGEN_FOUND)
 if (LLVM_ENABLE_DOXYGEN)

>From 584828b05034cffd28a87778e5c70c8575d81a5b Mon Sep 17 00:00:00 2001
From: Iuri Chaer <ichaer at splunk.com>
Date: Tue, 8 Oct 2024 10:57:02 +0100
Subject: [PATCH 2/2] REVERT BEFORE MERGING

Add a change to clang/include/clang/Format/Format.h so we can see the new CI check working.
---
 clang/include/clang/Format/Format.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/clang/include/clang/Format/Format.h b/clang/include/clang/Format/Format.h
index ef6c76a070bfaa..546b971a2ab35a 100644
--- a/clang/include/clang/Format/Format.h
+++ b/clang/include/clang/Format/Format.h
@@ -3791,7 +3791,7 @@ struct FormatStyle {
   enum ReferenceAlignmentStyle : int8_t {
     /// Align reference like ``PointerAlignment``.
     RAS_Pointer,
-    /// Align reference to the left.
+    /// Align reference to the left FOOBAR CHANGE TO VALIDATE NEW CI CHECK.
     /// \code
     ///   int& a;
     /// \endcode