1 # Copyright 2015 The Rust Project Developers. See the COPYRIGHT
2 # file at the top-level directory of this distribution and at
3 # http://rust-lang.org/COPYRIGHT.
5 # Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 # http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 # <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 # option. This file may not be copied, modified, or distributed
9 # except according to those terms.
12 htmldocck.py is a custom checker script for Rustdoc HTML outputs.
16 The principle is simple: This script receives a path to generated HTML
17 documentation and a "template" script, which has a series of check
18 commands like `@has` or `@matches`. Each command can be used to check if
19 some pattern is present or not present in the particular file or in
20 the particular node of HTML tree. In many cases, the template script
21 happens to be a source code given to rustdoc.
23 While it indeed is possible to test in smaller portions, it has been
24 hard to construct tests in this fashion and major rendering errors were
25 discovered much later. This script is designed for making the black-box
26 and regression testing of Rustdoc easy. This does not preclude the needs
27 for unit testing, but can be used to complement related tests by quickly
28 showing the expected renderings.
30 In order to avoid one-off dependencies for this task, this script uses
31 a reasonably working HTML parser and the existing XPath implementation
32 from Python's standard library. Hopefully we won't render
37 Commands start with an `@` followed by a command name (letters and
38 hyphens), and zero or more arguments separated by one or more whitespace
39 and optionally delimited with single or double quotes. The `@` mark
40 cannot be preceded by a non-whitespace character. Other lines (including
41 every text up to the first `@`) are ignored, but it is recommended to
42 avoid the use of `@` in the template file.
44 There are a number of supported commands:
46 * `@has PATH` checks for the existence of given file.
48 `PATH` is relative to the output directory. It can be given as `-`
49 which repeats the most recently used `PATH`.
51 * `@has PATH PATTERN` and `@matches PATH PATTERN` checks for
52 the occurrence of given `PATTERN` in the given file. Only one
53 occurrence of given pattern is enough.
55 For `@has`, `PATTERN` is a whitespace-normalized (every consecutive
56 whitespace being replaced by one single space character) string.
57 The entire file is also whitespace-normalized including newlines.
59 For `@matches`, `PATTERN` is a Python-supported regular expression.
60 The file remains intact but the regexp is matched with no `MULTILINE`
61 and `IGNORECASE` option. You can still use a prefix `(?m)` or `(?i)`
62 to override them, and `\A` and `\Z` for definitely matching
63 the beginning and end of the file.
65 (The same distinction goes to other variants of these commands.)
67 * `@has PATH XPATH PATTERN` and `@matches PATH XPATH PATTERN` checks for
68 the presence of given `XPATH` in the given HTML file, and also
69 the occurrence of given `PATTERN` in the matching node or attribute.
70 Only one occurrence of given pattern in the match is enough.
72 `PATH` should be a valid and well-formed HTML file. It does *not*
73 accept arbitrary HTML5; it should have matching open and close tags
74 and correct entity references at least.
76 `XPATH` is an XPath expression to match. This is fairly limited:
77 `tag`, `*`, `.`, `//`, `..`, `[@attr]`, `[@attr='value']`, `[tag]`,
78 `[POS]` (element located in given `POS`), `[last()-POS]`, `text()`
79 and `@attr` (both as the last segment) are supported. Some examples:
81 - `//pre` or `.//pre` matches any element with a name `pre`.
82 - `//a[@href]` matches any element with an `href` attribute.
83 - `//*[@class="impl"]//code` matches any element with a name `code`,
84 which is an ancestor of some element which `class` attr is `impl`.
85 - `//h1[@class="fqn"]/span[1]/a[last()]/@class` matches a value of
86 `class` attribute in the last `a` element (can be followed by more
87 elements that are not `a`) inside the first `span` in the `h1` with
88 a class of `fqn`. Note that there cannot be no additional elements
89 between them due to the use of `/` instead of `//`.
91 Do not try to use non-absolute paths, it won't work due to the flawed
92 ElementTree implementation. The script rejects them.
94 For the text matches (i.e. paths not ending with `@attr`), any
95 subelements are flattened into one string; this is handy for ignoring
96 highlights for example. If you want to simply check the presence of
97 given node or attribute, use an empty string (`""`) as a `PATTERN`.
99 * `@count PATH XPATH COUNT' checks for the occurrence of given XPath
100 in the given file. The number of occurrences must match the given count.
102 * `@has-dir PATH` checks for the existence of the given directory.
104 All conditions can be negated with `!`. `@!has foo/type.NoSuch.html`
105 checks if the given file does not exist, for example.
109 from __future__ import print_function
114 from collections import namedtuple
116 from html.parser import HTMLParser
118 from HTMLParser import HTMLParser
119 from xml.etree import cElementTree as ET
121 # ⇤/⇥ are not in HTML 4 but are in HTML 5
123 from html.entities import entitydefs
125 from htmlentitydefs import entitydefs
126 entitydefs['larrb'] = u'\u21e4'
127 entitydefs['rarrb'] = u'\u21e5'
128 entitydefs['nbsp'] = ' '
130 # "void elements" (no closing tag) from the HTML Standard section 12.1.2
131 VOID_ELEMENTS = set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'keygen',
132 'link', 'menuitem', 'meta', 'param', 'source', 'track', 'wbr'])
134 # Python 2 -> 3 compatibility
140 class CustomHTMLParser(HTMLParser):
141 """simplified HTML parser.
143 this is possible because we are dealing with very regular HTML from
144 rustdoc; we only have to deal with i) void elements and ii) empty
146 def __init__(self, target=None):
147 HTMLParser.__init__(self)
148 self.__builder = target or ET.TreeBuilder()
150 def handle_starttag(self, tag, attrs):
151 attrs = dict((k, v or '') for k, v in attrs)
152 self.__builder.start(tag, attrs)
153 if tag in VOID_ELEMENTS:
154 self.__builder.end(tag)
156 def handle_endtag(self, tag):
157 self.__builder.end(tag)
159 def handle_startendtag(self, tag, attrs):
160 attrs = dict((k, v or '') for k, v in attrs)
161 self.__builder.start(tag, attrs)
162 self.__builder.end(tag)
164 def handle_data(self, data):
165 self.__builder.data(data)
167 def handle_entityref(self, name):
168 self.__builder.data(entitydefs[name])
170 def handle_charref(self, name):
171 code = int(name[1:], 16) if name.startswith(('x', 'X')) else int(name, 10)
172 self.__builder.data(unichr(code).encode('utf-8'))
175 HTMLParser.close(self)
176 return self.__builder.close()
178 Command = namedtuple('Command', 'negated cmd args lineno context')
180 class FailedCheck(Exception):
183 class InvalidCheck(Exception):
186 def concat_multi_lines(f):
187 """returns a generator out of the file object, which
188 - removes `\\` then `\n` then a shared prefix with the previous line then
190 - keeps a line number (starting from 0) of the first line being
192 lastline = None # set to the last line when the last line has a backslash
195 for lineno, line in enumerate(f):
196 line = line.rstrip('\r\n')
198 # strip the common prefix from the current line if needed
199 if lastline is not None:
200 common_prefix = os.path.commonprefix([line, lastline])
201 line = line[len(common_prefix):].lstrip()
203 firstlineno = firstlineno or lineno
204 if line.endswith('\\'):
207 catenated += line[:-1]
209 yield firstlineno, catenated + line
214 if lastline is not None:
215 print_err(lineno, line, 'Trailing backslash at the end of the file')
217 LINE_PATTERN = re.compile(r'''
218 (?<=(?<!\S)@)(?P<negated>!?)
219 (?P<cmd>[A-Za-z]+(?:-[A-Za-z]+)*)
224 def get_commands(template):
225 with open(template, 'rU') as f:
226 for lineno, line in concat_multi_lines(f):
227 m = LINE_PATTERN.search(line)
231 negated = (m.group('negated') == '!')
233 args = m.group('args')
234 if args and not args[:1].isspace():
235 print_err(lineno, line, 'Invalid template syntax')
237 args = shlex.split(args)
238 yield Command(negated=negated, cmd=cmd, args=args, lineno=lineno+1, context=line)
241 def _flatten(node, acc):
243 acc.append(node.text)
256 def normalize_xpath(path):
257 if path.startswith('//'):
258 return '.' + path # avoid warnings
259 elif path.startswith('.//'):
262 raise InvalidCheck('Non-absolute XPath is not supported due to implementation issues')
265 class CachedFiles(object):
266 def __init__(self, root):
270 self.last_path = None
272 def resolve_path(self, path):
274 path = os.path.normpath(path)
275 self.last_path = path
277 elif self.last_path is None:
278 raise InvalidCheck('Tried to use the previous path in the first command')
280 return self.last_path
282 def get_file(self, path):
283 path = self.resolve_path(path)
284 if path in self.files:
285 return self.files[path]
287 abspath = os.path.join(self.root, path)
288 if not(os.path.exists(abspath) and os.path.isfile(abspath)):
289 raise FailedCheck('File does not exist {!r}'.format(path))
291 with open(abspath) as f:
293 self.files[path] = data
296 def get_tree(self, path):
297 path = self.resolve_path(path)
298 if path in self.trees:
299 return self.trees[path]
301 abspath = os.path.join(self.root, path)
302 if not(os.path.exists(abspath) and os.path.isfile(abspath)):
303 raise FailedCheck('File does not exist {!r}'.format(path))
305 with open(abspath) as f:
307 tree = ET.parse(f, CustomHTMLParser())
308 except Exception as e:
309 raise RuntimeError('Cannot parse an HTML file {!r}: {}'.format(path, e))
310 self.trees[path] = tree
311 return self.trees[path]
313 def get_dir(self, path):
314 path = self.resolve_path(path)
315 abspath = os.path.join(self.root, path)
316 if not(os.path.exists(abspath) and os.path.isdir(abspath)):
317 raise FailedCheck('Directory does not exist {!r}'.format(path))
320 def check_string(data, pat, regexp):
322 return True # special case a presence testing
324 return re.search(pat, data) is not None
326 data = ' '.join(data.split())
327 pat = ' '.join(pat.split())
331 def check_tree_attr(tree, path, attr, pat, regexp):
332 path = normalize_xpath(path)
334 for e in tree.findall(path):
336 value = e.attrib[attr]
340 ret = check_string(value, pat, regexp)
346 def check_tree_text(tree, path, pat, regexp):
347 path = normalize_xpath(path)
350 for e in tree.findall(path):
356 ret = check_string(value, pat, regexp)
359 except Exception as e:
360 print('Failed to get path "{}"'.format(path))
365 def get_tree_count(tree, path):
366 path = normalize_xpath(path)
367 return len(tree.findall(path))
370 print(*args, file=sys.stderr)
372 def print_err(lineno, context, err, message=None):
375 stderr("{}: {}".format(lineno, message or err))
377 stderr("\t{}".format(err))
380 stderr("\t{}".format(context))
384 def check_command(c, cache):
387 if c.cmd == 'has' or c.cmd == 'matches': # string test
388 regexp = (c.cmd == 'matches')
389 if len(c.args) == 1 and not regexp: # @has <path> = file existence
391 cache.get_file(c.args[0])
393 except FailedCheck as err:
396 elif len(c.args) == 2: # @has/matches <path> <pat> = string test
397 cerr = "`PATTERN` did not match"
398 ret = check_string(cache.get_file(c.args[0]), c.args[1], regexp)
399 elif len(c.args) == 3: # @has/matches <path> <pat> <match> = XML tree test
400 cerr = "`XPATH PATTERN` did not match"
401 tree = cache.get_tree(c.args[0])
402 pat, sep, attr = c.args[1].partition('/@')
404 tree = cache.get_tree(c.args[0])
405 ret = check_tree_attr(tree, pat, attr, c.args[2], regexp)
406 else: # normalized text
408 if pat.endswith('/text()'):
410 ret = check_tree_text(cache.get_tree(c.args[0]), pat, c.args[2], regexp)
412 raise InvalidCheck('Invalid number of @{} arguments'.format(c.cmd))
414 elif c.cmd == 'count': # count test
415 if len(c.args) == 3: # @count <path> <pat> <count> = count test
416 expected = int(c.args[2])
417 found = get_tree_count(cache.get_tree(c.args[0]), c.args[1])
418 cerr = "Expected {} occurrences but found {}".format(expected, found)
419 ret = expected == found
421 raise InvalidCheck('Invalid number of @{} arguments'.format(c.cmd))
422 elif c.cmd == 'has-dir': # has-dir test
423 if len(c.args) == 1: # @has-dir <path> = has-dir test
425 cache.get_dir(c.args[0])
427 except FailedCheck as err:
431 raise InvalidCheck('Invalid number of @{} arguments'.format(c.cmd))
432 elif c.cmd == 'valid-html':
433 raise InvalidCheck('Unimplemented @valid-html')
435 elif c.cmd == 'valid-links':
436 raise InvalidCheck('Unimplemented @valid-links')
438 raise InvalidCheck('Unrecognized @{}'.format(c.cmd))
441 raise FailedCheck(cerr)
443 except FailedCheck as err:
444 message = '@{}{} check failed'.format('!' if c.negated else '', c.cmd)
445 print_err(c.lineno, c.context, str(err), message)
446 except InvalidCheck as err:
447 print_err(c.lineno, c.context, str(err))
449 def check(target, commands):
450 cache = CachedFiles(target)
452 check_command(c, cache)
454 if __name__ == '__main__':
455 if len(sys.argv) != 3:
456 stderr('Usage: {} <doc dir> <template>'.format(sys.argv[0]))
459 check(sys.argv[1], get_commands(sys.argv[2]))
461 stderr("\nEncountered {} errors".format(ERR_COUNT))