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
184
185
186
187
188
189
190
191
192
193
194
|
/*
* Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
import doccheckutils.FileChecker;
import doccheckutils.FileProcessor;
import doccheckutils.HtmlFileChecker;
import doccheckutils.checkers.BadCharacterChecker;
import doccheckutils.checkers.DocTypeChecker;
import doccheckutils.checkers.LinkChecker;
import doccheckutils.checkers.TidyChecker;
import doccheckutils.checkers.ExtLinkChecker;
import toolbox.TestRunner;
import java.nio.file.Path;
import java.util.*;
/**
* DocCheck
* <p>
* For the sake of brevity, to run all of these checkers use
* <p>
* `make test-docs_all TEST_DEPS=docs-jdk`
* <p>
* This collection of tests provide a variety of checks for JDK documentation bundle.
* <p>
* It is meant to provide a convenient way to alert users of any errors in their documentation
* before a push and verify the quality of the documentation.
* It is not meant to replace more authoritative checkers; instead,
* it is more focused on providing a convenient, easy overview of any possible issues.
* <p>
* It supports the following checks:
* <p>
* *HTML* -- We use the standard `tidy` utility to check for HTML compliance,
* according to the declared version of HTML.
* The output from `tidy` is analysed to generate a report summarizing any issues that were found.
* <p>
* Version `5.9.20` of `tidy` is expected, or the output from the `--version` option should contain the string `version 5`.
* The test warns the user if he is using an earlier version.
* <p>
* *Bad Characters* -- We assumee that HTML files are encoded in UTF-8,
* and reports any character encoding issues that it finds.
* <p>
* *DocType* -- We assume that HTML files should use HTML5, and reports
* any files for which that is not the case.
* <p>
* *Links* -- We check links within a set of files, and reports on links
* to external resources, without otherwise checking them.
* <p>
* *External Links* -- We scan the files for URLs that refer to
* external resources, and validates those references using a "golden file" that includes a list of vetted links.
* <p>
* Each external reference is only checked once; but if an issue is found, all the files containing the
* reference will be reported.
*/
public class DocCheck extends TestRunner {
private static final String DOCCHECK_DIR = System.getProperty("doccheck.dir");
private static final Path DIR = Path.of(DOCCHECK_DIR != null ? DOCCHECK_DIR : "");
private static final Set<String> CHECKS_LIST = new HashSet<>();
private static Path DOCS_DIR;
private static boolean html;
private static boolean links;
private static boolean badchars;
private static boolean doctype;
private static boolean extlinks;
private List<Path> files;
public DocCheck() {
super(System.err);
init();
}
public static void main(String... args) throws Exception {
chooseCheckers();
DocCheck docCheck = new DocCheck();
docCheck.runTests();
}
private static void chooseCheckers() {
final String checks = System.getProperty("doccheck.checks");
if (!checks.isEmpty()) {
if (checks.contains(",")) {
CHECKS_LIST.addAll(Arrays.asList(checks.split(",")));
} else {
CHECKS_LIST.add(checks);
}
}
if (CHECKS_LIST.contains("all")) {
html = true;
links = true;
badchars = true;
doctype = true;
extlinks = true;
} else {
if (CHECKS_LIST.contains("html")) {
html = true;
}
if (CHECKS_LIST.contains("links")) {
links = true;
}
if (CHECKS_LIST.contains("badchars")) {
badchars = true;
}
if (CHECKS_LIST.contains("doctype")) {
doctype = true;
}
if (CHECKS_LIST.contains("extlinks")) {
extlinks = true;
}
}
}
public void init() {
var fileTester = new FileProcessor();
DOCS_DIR = DocTester.resolveDocs();
var baseDir = DOCS_DIR.resolve(DIR);
fileTester.processFiles(baseDir);
files = fileTester.getFiles();
}
public List<FileChecker> getCheckers() {
List<FileChecker> checkers = new ArrayList<>();
if (html) {
checkers.add(new TidyChecker());
}
if (links) {
var linkChecker = new LinkChecker();
linkChecker.setBaseDir(DOCS_DIR);
checkers.add(new HtmlFileChecker(linkChecker, DOCS_DIR));
}
if (extlinks) {
checkers.add(new HtmlFileChecker(new ExtLinkChecker(), DOCS_DIR));
}
// there should be almost nothing reported from these two checkers
// most reports should be broken anchors/links, missing files and errors in html
if (badchars) {
checkers.add(new BadCharacterChecker());
}
if (doctype) {
checkers.add(new HtmlFileChecker(new DocTypeChecker(), DOCS_DIR));
}
return checkers;
}
@Test
public void test() throws Exception {
List<FileChecker> checkers = getCheckers();
runCheckersSequentially(checkers);
}
private void runCheckersSequentially(List<FileChecker> checkers) throws Exception {
List<Throwable> exceptions = new ArrayList<>();
for (FileChecker checker : checkers) {
try (checker) {
checker.checkFiles(files);
} catch (Exception e) {
exceptions.add(e);
}
}
if (!exceptions.isEmpty()) {
throw new Exception("One or more HTML checkers failed: " + exceptions);
}
}
}
|
