Fixes https://github.com/llvm/llvm-project/issues/54418.
Reviewed By: MyDeveloperDay
Differential Revision: https://reviews.llvm.org/D121916
: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
-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).
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
--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``
--- /dev/null
+#!/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-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>
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>