1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
"""
Generates documentation based off the available static analyzers checks
References Checkers.td to determine what checks exist
"""
import argparse
import subprocess
import json
import os
import re
"""Get path of script so files are always in correct directory"""
__location__ = os.path.realpath(os.path.join(os.getcwd(), os.path.dirname(__file__)))
"""Get dict of checker related info and parse for full check names
Returns:
checkers: dict of checker info
"""
def get_checkers(checkers_td_directory):
p = subprocess.Popen(
[
"llvm-tblgen",
"--dump-json",
"-I",
checkers_td_directory,
checkers_td_directory + "Checkers.td",
],
stdout=subprocess.PIPE,
)
table_entries = json.loads(p.communicate()[0])
documentable_checkers = []
checkers = table_entries["!instanceof"]["Checker"]
packages = table_entries["!instanceof"]["Package"]
for checker_ in checkers:
checker = table_entries[checker_]
checker_name = checker["CheckerName"]
package_ = checker["ParentPackage"]["def"]
package = table_entries[package_]
package_name = package["PackageName"]
checker_package_prefix = package_name
parent_package_ = package["ParentPackage"]
hidden = (checker["Hidden"] != 0) or (package["Hidden"] != 0)
while parent_package_ != None:
parent_package = table_entries[parent_package_["def"]]
checker_package_prefix = (
parent_package["PackageName"] + "." + checker_package_prefix
)
hidden = hidden or parent_package["Hidden"] != 0
parent_package_ = parent_package["ParentPackage"]
full_package_name = (
"clang-analyzer-" + checker_package_prefix + "." + checker_name
)
anchor_url = re.sub(
"\.", "-", checker_package_prefix + "." + checker_name
).lower()
if not hidden and "alpha" not in full_package_name.lower():
checker["FullPackageName"] = full_package_name
checker["AnchorUrl"] = anchor_url
documentable_checkers.append(checker)
documentable_checkers.sort(key=lambda x: x["FullPackageName"])
return documentable_checkers
"""Generate documentation for checker
Args:
checker: Checker for which to generate documentation.
only_help_text: Generate documentation based off the checker description.
Used when there is no other documentation to link to.
"""
def generate_documentation(checker, only_help_text=False):
with open(
os.path.join(__location__, checker["FullPackageName"] + ".rst"), "w"
) as f:
f.write(".. title:: clang-tidy - %s\n" % checker["FullPackageName"])
if not only_help_text:
f.write(".. meta::\n")
f.write(
" :http-equiv=refresh: 5;URL=https://clang.llvm.org/docs/analyzer/checkers.html#%s\n"
% checker["AnchorUrl"]
)
f.write("\n")
f.write("%s\n" % checker["FullPackageName"])
f.write("=" * len(checker["FullPackageName"]) + "\n")
f.write("\n")
if only_help_text:
f.write("%s\n" % checker["HelpText"])
else:
f.write(
"The %s check is an alias, please see\n" % checker["FullPackageName"]
)
f.write(
"`Clang Static Analyzer Available Checkers <https://clang.llvm.org/docs/analyzer/checkers.html#%s>`_\n"
% checker["AnchorUrl"]
)
f.write("for more information.\n")
f.close()
"""Update list.rst to include the new checks
Args:
checkers: dict acquired from get_checkers()
"""
def update_documentation_list(checkers):
with open(os.path.join(__location__, "list.rst"), "r+") as f:
f_text = f.read()
header, check_text = f_text.split(".. toctree::\n")
checks = check_text.split("\n")
for checker in checkers:
if (" %s" % checker["FullPackageName"]) not in checks:
checks.append(" %s" % checker["FullPackageName"])
checks.sort()
# Overwrite file with new data
f.seek(0)
f.write(header)
f.write(".. toctree::")
for check in checks:
f.write("%s\n" % check)
f.close()
default_path_monorepo = "../../../../clang/include/clang/StaticAnalyzer/Checkers/"
default_path_in_tree = "../../../../../include/clang/StaticAnalyzer/Checkers/"
def parse_arguments():
"""Set up and parse command-line arguments
Returns:
file_path: Path to Checkers.td"""
usage = """Parse Checkers.td to generate documentation for static analyzer checks"""
parse = argparse.ArgumentParser(description=usage)
file_path_help = """Path to Checkers directory
defaults to ../../../../clang/include/clang/StaticAnalyzer/Checkers/ if it exists
then to ../../../../../include/clang/StaticAnalyzer/Checkers/"""
default_path = None
if os.path.exists(default_path_monorepo):
default_path = default_path_monorepo
elif os.path.exists(default_path_in_tree):
default_path = default_path_in_tree
parse.add_argument(
"file", type=str, help=file_path_help, nargs="?", default=default_path
)
args = parse.parse_args()
if args.file is None:
print("Could not find Checkers directory. Please see -h")
exit(1)
return args.file
def main():
file_path = parse_arguments()
checkers = get_checkers(file_path)
for checker in checkers:
# No documentation nor alpha documentation
if checker["Documentation"][1] == 0 and checker["Documentation"][0] == 0:
generate_documentation(checker, True)
else:
generate_documentation(checker)
print("Generated documentation for: %s" % checker["FullPackageName"])
update_documentation_list(checkers)
if __name__ == "__main__":
main()
|
