[clang] [clang-format][CMake] Generate formatting options docs during build (PR #113739)
via cfe-commits
cfe-commits at lists.llvm.org
Fri Oct 25 14:38:47 PDT 2024
llvmbot wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-clang
Author: Aiden Grossman (boomanaiden154)
<details>
<summary>Changes</summary>
This patch changes up the CMake configuration so that ClangFormatStyleOptions.rst has the format style options section generated by the dump_format_style.py python script during the build rather than manually. This allows us to remove ~6000 lines of automatically generated documentation from the repository.
If the context of the options is needed while generating the docs, it is easy enough to open up the generated file with the options from within the build directory after the clang-format-style-options target has been built.
---
Patch is 181.72 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/113739.diff
3 Files Affected:
- (modified) clang/docs/CMakeLists.txt (+10-1)
- (modified) clang/docs/ClangFormatStyleOptions.rst (+2-6649)
- (modified) clang/docs/tools/dump_format_style.py (+1-1)
``````````diff
diff --git a/clang/docs/CMakeLists.txt b/clang/docs/CMakeLists.txt
index 4fecc007f59954..313b0efd1dbd64 100644
--- a/clang/docs/CMakeLists.txt
+++ b/clang/docs/CMakeLists.txt
@@ -143,8 +143,17 @@ if (LLVM_ENABLE_SPHINX)
gen_rst_file_from_td(DiagnosticsReference.rst -gen-diag-docs ../include/clang/Basic/Diagnostic.td "${docs_targets}")
gen_rst_file_from_td(ClangCommandLineReference.rst -gen-opt-docs ../include/clang/Driver/ClangOptionDocs.td "${docs_targets}")
+ add_custom_target(clang-format-style-options
+ COMMAND "${Python3_EXECUTABLE}" "${CLANG_SOURCE_DIR}/docs/tools/dump_format_style.py"
+ WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"
+ DEPENDS "${CLANG_SOURCE_DIR}/include/clang/Format/Format.h"
+ "${CLANG_SOURCE_DIR}/include/clang/Tooling/Inclusions/IncludeStyle.h"
+ "${CLANG_SOURCE_DIR}/docs/tools/dump_format_style.py"
+ copy-clang-rst-docs
+ )
+
foreach(target ${docs_targets})
- add_dependencies(${target} copy-clang-rst-docs)
+ add_dependencies(${target} copy-clang-rst-docs clang-format-style-options)
endforeach()
endif()
endif()
diff --git a/clang/docs/ClangFormatStyleOptions.rst b/clang/docs/ClangFormatStyleOptions.rst
index 9ef1fd5f36d1d3..508a058de6f768 100644
--- a/clang/docs/ClangFormatStyleOptions.rst
+++ b/clang/docs/ClangFormatStyleOptions.rst
@@ -1,9 +1,3 @@
-..
- !!!!NOTE!!!!
- This file is automatically generated, in part. Do not edit the style options
- in this file directly. Instead, modify them in include/clang/Format/Format.h
- and run the docs/tools/dump_format_style.py script to update this file.
-
.. raw:: html
<style type="text/css">
@@ -185,6651 +179,10 @@ the configuration (without a prefix: ``Auto``).
subdirectories. This is also possible through the command line, e.g.:
``--style={BasedOnStyle: InheritParentConfig, ColumnLimit: 20}``
+.. This section of the file is automatically generated by the
+ dump_format_style.py tool and should be updated manually.
.. START_FORMAT_STYLE_OPTIONS
-.. _AccessModifierOffset:
-
-**AccessModifierOffset** (``Integer``) :versionbadge:`clang-format 3.3` :ref:`¶ <AccessModifierOffset>`
- The extra indent or outdent of access modifiers, e.g. ``public:``.
-
-.. _AlignAfterOpenBracket:
-
-**AlignAfterOpenBracket** (``BracketAlignmentStyle``) :versionbadge:`clang-format 3.8` :ref:`¶ <AlignAfterOpenBracket>`
- If ``true``, horizontally aligns arguments after an open bracket.
-
- This applies to round brackets (parentheses), angle brackets and square
- brackets.
-
- Possible values:
-
- * ``BAS_Align`` (in configuration: ``Align``)
- Align parameters on the open bracket, e.g.:
-
- .. code-block:: c++
-
- someLongFunction(argument1,
- argument2);
-
- * ``BAS_DontAlign`` (in configuration: ``DontAlign``)
- Don't align, instead use ``ContinuationIndentWidth``, e.g.:
-
- .. code-block:: c++
-
- someLongFunction(argument1,
- argument2);
-
- * ``BAS_AlwaysBreak`` (in configuration: ``AlwaysBreak``)
- Always break after an open bracket, if the parameters don't fit
- on a single line, e.g.:
-
- .. code-block:: c++
-
- someLongFunction(
- argument1, argument2);
-
- * ``BAS_BlockIndent`` (in configuration: ``BlockIndent``)
- Always break after an open bracket, if the parameters don't fit
- on a single line. Closing brackets will be placed on a new line.
- E.g.:
-
- .. code-block:: c++
-
- someLongFunction(
- argument1, argument2
- )
-
-
- .. note::
-
- This currently only applies to braced initializer lists (when
- ``Cpp11BracedListStyle`` is ``true``) and parentheses.
-
-
-
-.. _AlignArrayOfStructures:
-
-**AlignArrayOfStructures** (``ArrayInitializerAlignmentStyle``) :versionbadge:`clang-format 13` :ref:`¶ <AlignArrayOfStructures>`
- If not ``None``, when using initialization for an array of structs
- aligns the fields into columns.
-
-
- .. note::
-
- As of clang-format 15 this option only applied to arrays with equal
- number of columns per row.
-
- Possible values:
-
- * ``AIAS_Left`` (in configuration: ``Left``)
- Align array column and left justify the columns e.g.:
-
- .. code-block:: c++
-
- struct test demo[] =
- {
- {56, 23, "hello"},
- {-1, 93463, "world"},
- {7, 5, "!!" }
- };
-
- * ``AIAS_Right`` (in configuration: ``Right``)
- Align array column and right justify the columns e.g.:
-
- .. code-block:: c++
-
- struct test demo[] =
- {
- {56, 23, "hello"},
- {-1, 93463, "world"},
- { 7, 5, "!!"}
- };
-
- * ``AIAS_None`` (in configuration: ``None``)
- Don't align array initializer columns.
-
-
-
-.. _AlignConsecutiveAssignments:
-
-**AlignConsecutiveAssignments** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 3.8` :ref:`¶ <AlignConsecutiveAssignments>`
- Style of aligning consecutive assignments.
-
- ``Consecutive`` will result in formattings like:
-
- .. code-block:: c++
-
- int a = 1;
- int somelongname = 2;
- double c = 3;
-
- Nested configuration flags:
-
- Alignment options.
-
- They can also be read as a whole for compatibility. The choices are:
-
- * ``None``
- * ``Consecutive``
- * ``AcrossEmptyLines``
- * ``AcrossComments``
- * ``AcrossEmptyLinesAndComments``
-
- For example, to align across empty lines and not across comments, either
- of these work.
-
- .. code-block:: c++
-
- AlignConsecutiveAssignments: AcrossEmptyLines
-
- AlignConsecutiveAssignments:
- Enabled: true
- AcrossEmptyLines: true
- AcrossComments: false
-
- * ``bool Enabled`` Whether aligning is enabled.
-
- .. code-block:: c++
-
- #define SHORT_NAME 42
- #define LONGER_NAME 0x007f
- #define EVEN_LONGER_NAME (2)
- #define foo(x) (x * x)
- #define bar(y, z) (y + z)
-
- int a = 1;
- int somelongname = 2;
- double c = 3;
-
- int aaaa : 1;
- int b : 12;
- int ccc : 8;
-
- int aaaa = 12;
- float b = 23;
- std::string ccc;
-
- * ``bool AcrossEmptyLines`` Whether to align across empty lines.
-
- .. code-block:: c++
-
- true:
- int a = 1;
- int somelongname = 2;
- double c = 3;
-
- int d = 3;
-
- false:
- int a = 1;
- int somelongname = 2;
- double c = 3;
-
- int d = 3;
-
- * ``bool AcrossComments`` Whether to align across comments.
-
- .. code-block:: c++
-
- true:
- int d = 3;
- /* A comment. */
- double e = 4;
-
- false:
- int d = 3;
- /* A comment. */
- double e = 4;
-
- * ``bool AlignCompound`` Only for ``AlignConsecutiveAssignments``. Whether compound assignments
- like ``+=`` are aligned along with ``=``.
-
- .. code-block:: c++
-
- true:
- a &= 2;
- bbb = 2;
-
- false:
- a &= 2;
- bbb = 2;
-
- * ``bool AlignFunctionDeclarations`` Only for ``AlignConsecutiveDeclarations``. Whether function declarations
- are aligned.
-
- .. code-block:: c++
-
- true:
- unsigned int f1(void);
- void f2(void);
- size_t f3(void);
-
- false:
- unsigned int f1(void);
- void f2(void);
- size_t f3(void);
-
- * ``bool AlignFunctionPointers`` Only for ``AlignConsecutiveDeclarations``. Whether function pointers are
- aligned.
-
- .. code-block:: c++
-
- true:
- unsigned i;
- int &r;
- int *p;
- int (*f)();
-
- false:
- unsigned i;
- int &r;
- int *p;
- int (*f)();
-
- * ``bool PadOperators`` Only for ``AlignConsecutiveAssignments``. Whether short assignment
- operators are left-padded to the same length as long ones in order to
- put all assignment operators to the right of the left hand side.
-
- .. code-block:: c++
-
- true:
- a >>= 2;
- bbb = 2;
-
- a = 2;
- bbb >>= 2;
-
- false:
- a >>= 2;
- bbb = 2;
-
- a = 2;
- bbb >>= 2;
-
-
-.. _AlignConsecutiveBitFields:
-
-**AlignConsecutiveBitFields** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 11` :ref:`¶ <AlignConsecutiveBitFields>`
- Style of aligning consecutive bit fields.
-
- ``Consecutive`` will align the bitfield separators of consecutive lines.
- This will result in formattings like:
-
- .. code-block:: c++
-
- int aaaa : 1;
- int b : 12;
- int ccc : 8;
-
- Nested configuration flags:
-
- Alignment options.
-
- They can also be read as a whole for compatibility. The choices are:
-
- * ``None``
- * ``Consecutive``
- * ``AcrossEmptyLines``
- * ``AcrossComments``
- * ``AcrossEmptyLinesAndComments``
-
- For example, to align across empty lines and not across comments, either
- of these work.
-
- .. code-block:: c++
-
- AlignConsecutiveBitFields: AcrossEmptyLines
-
- AlignConsecutiveBitFields:
- Enabled: true
- AcrossEmptyLines: true
- AcrossComments: false
-
- * ``bool Enabled`` Whether aligning is enabled.
-
- .. code-block:: c++
-
- #define SHORT_NAME 42
- #define LONGER_NAME 0x007f
- #define EVEN_LONGER_NAME (2)
- #define foo(x) (x * x)
- #define bar(y, z) (y + z)
-
- int a = 1;
- int somelongname = 2;
- double c = 3;
-
- int aaaa : 1;
- int b : 12;
- int ccc : 8;
-
- int aaaa = 12;
- float b = 23;
- std::string ccc;
-
- * ``bool AcrossEmptyLines`` Whether to align across empty lines.
-
- .. code-block:: c++
-
- true:
- int a = 1;
- int somelongname = 2;
- double c = 3;
-
- int d = 3;
-
- false:
- int a = 1;
- int somelongname = 2;
- double c = 3;
-
- int d = 3;
-
- * ``bool AcrossComments`` Whether to align across comments.
-
- .. code-block:: c++
-
- true:
- int d = 3;
- /* A comment. */
- double e = 4;
-
- false:
- int d = 3;
- /* A comment. */
- double e = 4;
-
- * ``bool AlignCompound`` Only for ``AlignConsecutiveAssignments``. Whether compound assignments
- like ``+=`` are aligned along with ``=``.
-
- .. code-block:: c++
-
- true:
- a &= 2;
- bbb = 2;
-
- false:
- a &= 2;
- bbb = 2;
-
- * ``bool AlignFunctionDeclarations`` Only for ``AlignConsecutiveDeclarations``. Whether function declarations
- are aligned.
-
- .. code-block:: c++
-
- true:
- unsigned int f1(void);
- void f2(void);
- size_t f3(void);
-
- false:
- unsigned int f1(void);
- void f2(void);
- size_t f3(void);
-
- * ``bool AlignFunctionPointers`` Only for ``AlignConsecutiveDeclarations``. Whether function pointers are
- aligned.
-
- .. code-block:: c++
-
- true:
- unsigned i;
- int &r;
- int *p;
- int (*f)();
-
- false:
- unsigned i;
- int &r;
- int *p;
- int (*f)();
-
- * ``bool PadOperators`` Only for ``AlignConsecutiveAssignments``. Whether short assignment
- operators are left-padded to the same length as long ones in order to
- put all assignment operators to the right of the left hand side.
-
- .. code-block:: c++
-
- true:
- a >>= 2;
- bbb = 2;
-
- a = 2;
- bbb >>= 2;
-
- false:
- a >>= 2;
- bbb = 2;
-
- a = 2;
- bbb >>= 2;
-
-
-.. _AlignConsecutiveDeclarations:
-
-**AlignConsecutiveDeclarations** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 3.8` :ref:`¶ <AlignConsecutiveDeclarations>`
- Style of aligning consecutive declarations.
-
- ``Consecutive`` will align the declaration names of consecutive lines.
- This will result in formattings like:
-
- .. code-block:: c++
-
- int aaaa = 12;
- float b = 23;
- std::string ccc;
-
- Nested configuration flags:
-
- Alignment options.
-
- They can also be read as a whole for compatibility. The choices are:
-
- * ``None``
- * ``Consecutive``
- * ``AcrossEmptyLines``
- * ``AcrossComments``
- * ``AcrossEmptyLinesAndComments``
-
- For example, to align across empty lines and not across comments, either
- of these work.
-
- .. code-block:: c++
-
- AlignConsecutiveDeclarations: AcrossEmptyLines
-
- AlignConsecutiveDeclarations:
- Enabled: true
- AcrossEmptyLines: true
- AcrossComments: false
-
- * ``bool Enabled`` Whether aligning is enabled.
-
- .. code-block:: c++
-
- #define SHORT_NAME 42
- #define LONGER_NAME 0x007f
- #define EVEN_LONGER_NAME (2)
- #define foo(x) (x * x)
- #define bar(y, z) (y + z)
-
- int a = 1;
- int somelongname = 2;
- double c = 3;
-
- int aaaa : 1;
- int b : 12;
- int ccc : 8;
-
- int aaaa = 12;
- float b = 23;
- std::string ccc;
-
- * ``bool AcrossEmptyLines`` Whether to align across empty lines.
-
- .. code-block:: c++
-
- true:
- int a = 1;
- int somelongname = 2;
- double c = 3;
-
- int d = 3;
-
- false:
- int a = 1;
- int somelongname = 2;
- double c = 3;
-
- int d = 3;
-
- * ``bool AcrossComments`` Whether to align across comments.
-
- .. code-block:: c++
-
- true:
- int d = 3;
- /* A comment. */
- double e = 4;
-
- false:
- int d = 3;
- /* A comment. */
- double e = 4;
-
- * ``bool AlignCompound`` Only for ``AlignConsecutiveAssignments``. Whether compound assignments
- like ``+=`` are aligned along with ``=``.
-
- .. code-block:: c++
-
- true:
- a &= 2;
- bbb = 2;
-
- false:
- a &= 2;
- bbb = 2;
-
- * ``bool AlignFunctionDeclarations`` Only for ``AlignConsecutiveDeclarations``. Whether function declarations
- are aligned.
-
- .. code-block:: c++
-
- true:
- unsigned int f1(void);
- void f2(void);
- size_t f3(void);
-
- false:
- unsigned int f1(void);
- void f2(void);
- size_t f3(void);
-
- * ``bool AlignFunctionPointers`` Only for ``AlignConsecutiveDeclarations``. Whether function pointers are
- aligned.
-
- .. code-block:: c++
-
- true:
- unsigned i;
- int &r;
- int *p;
- int (*f)();
-
- false:
- unsigned i;
- int &r;
- int *p;
- int (*f)();
-
- * ``bool PadOperators`` Only for ``AlignConsecutiveAssignments``. Whether short assignment
- operators are left-padded to the same length as long ones in order to
- put all assignment operators to the right of the left hand side.
-
- .. code-block:: c++
-
- true:
- a >>= 2;
- bbb = 2;
-
- a = 2;
- bbb >>= 2;
-
- false:
- a >>= 2;
- bbb = 2;
-
- a = 2;
- bbb >>= 2;
-
-
-.. _AlignConsecutiveMacros:
-
-**AlignConsecutiveMacros** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 9` :ref:`¶ <AlignConsecutiveMacros>`
- Style of aligning consecutive macro definitions.
-
- ``Consecutive`` will result in formattings like:
-
- .. code-block:: c++
-
- #define SHORT_NAME 42
- #define LONGER_NAME 0x007f
- #define EVEN_LONGER_NAME (2)
- #define foo(x) (x * x)
- #define bar(y, z) (y + z)
-
- Nested configuration flags:
-
- Alignment options.
-
- They can also be read as a whole for compatibility. The choices are:
-
- * ``None``
- * ``Consecutive``
- * ``AcrossEmptyLines``
- * ``AcrossComments``
- * ``AcrossEmptyLinesAndComments``
-
- For example, to align across empty lines and not across comments, either
- of these work.
-
- .. code-block:: c++
-
- AlignConsecutiveMacros: AcrossEmptyLines
-
- AlignConsecutiveMacros:
- Enabled: true
- AcrossEmptyLines: true
- AcrossComments: false
-
- * ``bool Enabled`` Whether aligning is enabled.
-
- .. code-block:: c++
-
- #define SHORT_NAME 42
- #define LONGER_NAME 0x007f
- #define EVEN_LONGER_NAME (2)
- #define foo(x) (x * x)
- #define bar(y, z) (y + z)
-
- int a = 1;
- int somelongname = 2;
- double c = 3;
-
- int aaaa : 1;
- int b : 12;
- int ccc : 8;
-
- int aaaa = 12;
- float b = 23;
- std::string ccc;
-
- * ``bool AcrossEmptyLines`` Whether to align across empty lines.
-
- .. code-block:: c++
-
- true:
- int a = 1;
- int somelongname = 2;
- double c = 3;
-
- int d = 3;
-
- false:
- int a = 1;
- int somelongname = 2;
- double c = 3;
-
- int d = 3;
-
- * ``bool AcrossComments`` Whether to align across comments.
-
- .. code-block:: c++
-
- true:
- int d = 3;
- /* A comment. */
- double e = 4;
-
- false:
- int d = 3;
- /* A comment. */
- double e = 4;
-
- * ``bool AlignCompound`` Only for ``AlignConsecutiveAssignments``. Whether compound assignments
- like ``+=`` are aligned along with ``=``.
-
- .. code-block:: c++
-
- true:
- a &= 2;
- bbb = 2;
-
- false:
- a &= 2;
- bbb = 2;
-
- * ``bool AlignFunctionDeclarations`` Only for ``AlignConsecutiveDeclarations``. Whether function declarations
- are aligned.
-
- .. code-block:: c++
-
- true:
- unsigned int f1(void);
- void f2(void);
- size_t f3(void);
-
- false:
- unsigned int f1(void);
- void f2(void);
- size_t f3(void);
-
- * ``bool AlignFunctionPointers`` Only for ``AlignConsecutiveDeclarations``. Whether function pointers are
- aligned.
-
- .. code-block:: c++
-
- true:
- unsigned i;
- int &r;
- int *p;
- int (*f)();
-
- false:
- unsigned i;
- int &r;
- int *p;
- int (*f)();
-
- * ``bool PadOperators`` Only for ``AlignConsecutiveAssignments``. Whether short assignment
- operators are left-padded to the same length as long ones in order to
- put all assignment operators to the right of the left hand side.
-
- .. code-block:: c++
-
- true:
- a >>= 2;
- bbb = 2;
-
- a = 2;
- bbb >>= 2;
-
- false:
- a >>= 2;
- bbb = 2;
-
- a = 2;
- bbb >>= 2;
-
-
-.. _AlignConsecutiveShortCaseStatements:
-
-**AlignConsecutiveShortCaseStatements** (``ShortCaseStatementsAlignmentStyle``) :versionbadge:`clang-format 17` :ref:`¶ <AlignConsecutiveShortCaseStatements>`
- Style of aligning consecutive short case labels.
- Only applies if ``AllowShortCaseExpressionOnASingleLine`` or
- ``AllowShortCaseLabelsOnASingleLine`` is ``true``.
-
-
- .. code-block:: yaml
-
- # Example of usage:
- AlignConsecutiveShortCaseStatements:
- Enabled: true
- AcrossEmptyLines: true
- AcrossComments: true
- AlignCaseColons: false
-
- Nested configuration flags:
-
- Alignment options.
-
- * ``bool Enabled`` Whether aligning is enabled.
-
- .. code-block:: c++
-
- true:
- switch (level) {
- case log::info: return "info:";
- case log::warning: return "warning:";
- default: return "";
- }
-
- false:
- switch (level) {
- case log::info: return "info:";
- case log::warning: return "warning:";
- default: return "";
- }
-
- * ``bool AcrossEmptyLines`` Whether to align across empty lines.
-
- .. code-block:: c++
-
- true:
- switch (level) {
- case log::info: return "info:";
- case log::warning: return "warning:";
-
- default: return "";
- }
-
- false:
- switch (level) {
- case log::info: return "info:";
- case log::warning: return "warning:";
-
- default: return "";
- }
-
- * ``bool AcrossComments`` Whether to align across comments.
-
- .. code-block:: c++
-
- true:
- switch (level) {
- case log::info: return "info:";
- case log::w...
[truncated]
``````````
</details>
https://github.com/llvm/llvm-project/pull/113739
More information about the cfe-commits
mailing list