[clang] a45ad3c - [clang-format] [doc] Add script to automatically update help output in ClangFormat.rst.
Marek Kurdej via cfe-commits
cfe-commits at lists.llvm.org
Wed Mar 23 05:17:55 PDT 2022
Author: Marek Kurdej
Date: 2022-03-23T13:17:50+01:00
New Revision: a45ad3ca8ce78988a4d51b432455ce0ddddbbf13
URL: https://github.com/llvm/llvm-project/commit/a45ad3ca8ce78988a4d51b432455ce0ddddbbf13
DIFF: https://github.com/llvm/llvm-project/commit/a45ad3ca8ce78988a4d51b432455ce0ddddbbf13.diff
LOG: [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
Added:
clang/docs/tools/dump_format_help.py
Modified:
clang/docs/ClangFormat.rst
clang/tools/clang-format/ClangFormat.cpp
Removed:
################################################################################
diff --git a/clang/docs/ClangFormat.rst b/clang/docs/ClangFormat.rst
index 5fc9656a4756a..745c66efa9e0e 100644
--- a/clang/docs/ClangFormat.rst
+++ b/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
diff erent 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``
diff --git a/clang/docs/tools/dump_format_help.py b/clang/docs/tools/dump_format_help.py
new file mode 100644
index 0000000000000..68869d91056ce
--- /dev/null
+++ b/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())
diff --git a/clang/tools/clang-format/ClangFormat.cpp b/clang/tools/clang-format/ClangFormat.cpp
index 893c17d917082..5f7d65f9a1b0c 100644
--- a/clang/tools/clang-format/ClangFormat.cpp
+++ b/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>
More information about the cfe-commits
mailing list