[clang-format] [doc] Add script to automatically update help output in ClangFormat.rst.

Fixes https://github.com/llvm/llvm-project/issues/54418.

Reviewed By: MyDeveloperDay

Differential Revision: https://reviews.llvm.org/D121916

clang/docs/ClangFormat.rst

@@ -13,6 +13,8 @@ Standalone Tool
 :program:`clang-format` is located in `clang/tools/clang-format` and can be used
 to format C/C++/Java/JavaScript/JSON/Objective-C/Protobuf/C# code.
 
+.. START_FORMAT_HELP
+
 .. code-block:: console
 
   $ clang-format -help
@@ -51,7 +53,9 @@ to format C/C++/Java/JavaScript/JSON/Objective-C/Protobuf/C# code.
                                      -style=file, but can not find the .clang-format
                                      file to use.
                                      Use -fallback-style=none to skip formatting.
-    --ferror-limit=<uint>          - Set the maximum number of clang-format errors to emit before stopping (0 = no limit). Used only with --dry-run or -n
+    --ferror-limit=<uint>          - Set the maximum number of clang-format errors to emit
+                                     before stopping (0 = no limit).
+                                     Used only with --dry-run or -n
     --files=<string>               - Provide a list of files to run clang-format
     -i                             - Inplace edit <file>s, if specified.
     --length=<uint>                - Format a range of this length (in bytes).
@@ -73,8 +77,10 @@ to format C/C++/Java/JavaScript/JSON/Objective-C/Protobuf/C# code.
                                      several -offset and -length pairs.
                                      Can only be used with one input file.
     --output-replacements-xml      - Output replacements as XML.
-    --qualifier-alignment=<string> - If set, overrides the qualifier alignment style determined by the QualifierAlignment style flag
-    --sort-includes                - If set, overrides the include sorting behavior determined by the SortIncludes style flag
+    --qualifier-alignment=<string> - If set, overrides the qualifier alignment style
+                                     determined by the QualifierAlignment style flag
+    --sort-includes                - If set, overrides the include sorting behavior
+                                     determined by the SortIncludes style flag
     --style=<string>               - Coding style, currently supports:
                                        LLVM, GNU, Google, Chromium, Microsoft, Mozilla, WebKit.
                                      Use -style=file to load style configuration from
@@ -95,6 +101,8 @@ to format C/C++/Java/JavaScript/JSON/Objective-C/Protobuf/C# code.
     --version                      - Display the version of this program
 
 
+.. END_FORMAT_HELP
+
 When the desired code formatting style is different from the available options,
 the style can be customized using the ``-style="{key: value, ...}"`` option or
 by putting your style configuration in the ``.clang-format`` or ``_clang-format``

clang/docs/tools/dump_format_help.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+# A tool to parse the output of `clang-format --help` and update the
+# documentation in ../ClangFormat.rst automatically.
+
+import os
+import re
+import subprocess
+import sys
+
+CLANG_DIR = os.path.join(os.path.dirname(__file__), '../..')
+DOC_FILE = os.path.join(CLANG_DIR, 'docs/ClangFormat.rst')
+
+
+def substitute(text, tag, contents):
+    replacement = '\n.. START_%s\n\n%s\n\n.. END_%s\n' % (tag, contents, tag)
+    pattern = r'\n\.\. START_%s\n.*\n\.\. END_%s\n' % (tag, tag)
+    return re.sub(pattern, '%s', text, flags=re.S) % replacement
+
+
+def indent(text, columns, indent_first_line=True):
+    indent_str = ' ' * columns
+    s = re.sub(r'\n([^\n])', '\n' + indent_str + '\\1', text, flags=re.S)
+    if not indent_first_line or s.startswith('\n'):
+        return s
+    return indent_str + s
+
+
+def get_help_output():
+    args = ["clang-format", "--help"]
+    cmd = subprocess.Popen(args, stdout=subprocess.PIPE,
+                           stderr=subprocess.STDOUT)
+    out, _ = cmd.communicate()
+    out = out.decode(sys.stdout.encoding)
+    return out
+
+
+def get_help_text():
+    out = get_help_output()
+    out = re.sub(r' clang-format\.exe ', ' clang-format ', out)
+
+    out = '''.. code-block:: console
+
+$ clang-format -help
+''' + out
+    out = indent(out, 2, indent_first_line=False)
+    return out
+
+
+def validate(text, columns):
+    for line in text.splitlines():
+        if len(line) > columns:
+            print('warning: line too long:\n', line, file=sys.stderr)
+
+
+help_text = get_help_text()
+validate(help_text, 95)
+
+with open(DOC_FILE) as f:
+    contents = f.read()
+
+contents = substitute(contents, 'FORMAT_HELP', help_text)
+
+with open(DOC_FILE, 'wb') as output:
+    output.write(contents.encode())

clang/tools/clang-format/ClangFormat.cpp

@@ -100,17 +100,16 @@ static cl::opt<unsigned>
                     "clang-format from an editor integration"),
            cl::init(0), cl::cat(ClangFormatCategory));
 
-static cl::opt<bool> SortIncludes(
-    "sort-includes",
-    cl::desc("If set, overrides the include sorting behavior determined by the "
-             "SortIncludes style flag"),
-    cl::cat(ClangFormatCategory));
+static cl::opt<bool>
+    SortIncludes("sort-includes",
+                 cl::desc("If set, overrides the include sorting behavior\n"
+                          "determined by the SortIncludes style flag"),
+                 cl::cat(ClangFormatCategory));
 
 static cl::opt<std::string> QualifierAlignment(
     "qualifier-alignment",
-    cl::desc(
-        "If set, overrides the qualifier alignment style determined by the "
-        "QualifierAlignment style flag"),
+    cl::desc("If set, overrides the qualifier alignment style\n"
+             "determined by the QualifierAlignment style flag"),
     cl::init(""), cl::cat(ClangFormatCategory));
 
 static cl::opt<std::string>
@@ -148,8 +147,9 @@ static cl::opt<bool>
 
 static cl::opt<unsigned> ErrorLimit(
     "ferror-limit",
-    cl::desc("Set the maximum number of clang-format errors to emit before "
-             "stopping (0 = no limit). Used only with --dry-run or -n"),
+    cl::desc("Set the maximum number of clang-format errors to emit\n"
+             "before stopping (0 = no limit).\n"
+             "Used only with --dry-run or -n"),
     cl::init(0), cl::cat(ClangFormatCategory));
 
 static cl::opt<bool>