|
15 | 15 |
|
16 | 16 | The principle is simple: This script receives a path to generated HTML |
17 | 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 |
| 18 | +commands like `@has` or `@matches`. Each command is used to check if |
19 | 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. |
| 20 | +a particular node of the HTML tree. In many cases, the template script |
| 21 | +happens to be the source code given to rustdoc. |
22 | 22 |
|
23 | 23 | While it indeed is possible to test in smaller portions, it has been |
24 | 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 |
| 25 | +discovered much later. This script is designed to make black-box and |
| 26 | +regression testing of Rustdoc easy. This does not preclude the needs for |
| 27 | +unit testing, but can be used to complement related tests by quickly |
28 | 28 | showing the expected renderings. |
29 | 29 |
|
30 | 30 | In order to avoid one-off dependencies for this task, this script uses |
31 | 31 | a reasonably working HTML parser and the existing XPath implementation |
32 | | -from Python's standard library. Hopefully we won't render |
| 32 | +from Python's standard library. Hopefully, we won't render |
33 | 33 | non-well-formed HTML. |
34 | 34 |
|
35 | 35 | # Commands |
36 | 36 |
|
37 | 37 | Commands start with an `@` followed by a command name (letters and |
38 | 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. |
| 39 | +characters and optionally delimited with single or double quotes. The `@` |
| 40 | +mark cannot be preceded by a non-whitespace character. Other lines |
| 41 | +(including every text up to the first `@`) are ignored, but it is |
| 42 | +recommended to avoid the use of `@` in the template file. |
43 | 43 |
|
44 | 44 | There are a number of supported commands: |
45 | 45 |
|
46 | | -* `@has PATH` checks for the existence of given file. |
| 46 | +* `@has PATH` checks for the existence of the given file. |
47 | 47 |
|
48 | 48 | `PATH` is relative to the output directory. It can be given as `-` |
49 | 49 | which repeats the most recently used `PATH`. |
50 | 50 |
|
51 | 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. |
| 52 | + the occurrence of the given pattern `PATTERN` in the specified file. |
| 53 | + Only one occurrence of the pattern is enough. |
54 | 54 |
|
55 | 55 | For `@has`, `PATTERN` is a whitespace-normalized (every consecutive |
56 | 56 | whitespace being replaced by one single space character) string. |
57 | 57 | The entire file is also whitespace-normalized including newlines. |
58 | 58 |
|
59 | 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)` |
| 60 | + The file remains intact but the regexp is matched without the `MULTILINE` |
| 61 | + and `IGNORECASE` options. You can still use a prefix `(?m)` or `(?i)` |
62 | 62 | to override them, and `\A` and `\Z` for definitely matching |
63 | 63 | the beginning and end of the file. |
64 | 64 |
|
65 | 65 | (The same distinction goes to other variants of these commands.) |
66 | 66 |
|
67 | 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. |
| 68 | + the presence of the given XPath `XPATH` in the specified HTML file, |
| 69 | + and also the occurrence of the given pattern `PATTERN` in the matching |
| 70 | + node or attribute. Only one occurrence of the pattern in the match |
| 71 | + is enough. |
71 | 72 |
|
72 | 73 | `PATH` should be a valid and well-formed HTML file. It does *not* |
73 | 74 | accept arbitrary HTML5; it should have matching open and close tags |
74 | 75 | and correct entity references at least. |
75 | 76 |
|
76 | | - `XPATH` is an XPath expression to match. This is fairly limited: |
| 77 | + `XPATH` is an XPath expression to match. The XPath is fairly limited: |
77 | 78 | `tag`, `*`, `.`, `//`, `..`, `[@attr]`, `[@attr='value']`, `[tag]`, |
78 | 79 | `[POS]` (element located in given `POS`), `[last()-POS]`, `text()` |
79 | 80 | and `@attr` (both as the last segment) are supported. Some examples: |
|
85 | 86 | - `//h1[@class="fqn"]/span[1]/a[last()]/@class` matches a value of |
86 | 87 | `class` attribute in the last `a` element (can be followed by more |
87 | 88 | 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 | + a class of `fqn`. Note that there cannot be any additional elements |
89 | 90 | between them due to the use of `/` instead of `//`. |
90 | 91 |
|
91 | 92 | Do not try to use non-absolute paths, it won't work due to the flawed |
92 | 93 | ElementTree implementation. The script rejects them. |
93 | 94 |
|
94 | 95 | For the text matches (i.e. paths not ending with `@attr`), any |
95 | 96 | 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`. |
| 97 | + highlights for example. If you want to simply check for the presence of |
| 98 | + a given node or attribute, use an empty string (`""`) as a `PATTERN`. |
98 | 99 |
|
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. |
| 100 | +* `@count PATH XPATH COUNT' checks for the occurrence of the given XPath |
| 101 | + in the specified file. The number of occurrences must match the given |
| 102 | + count. |
101 | 103 |
|
102 | 104 | * `@has-dir PATH` checks for the existence of the given directory. |
103 | 105 |
|
|
0 commit comments