Skip to content

Commit 4cda7ac

Browse files
stragerstrager
committed
Website: generate error documentation from .md files
Our quick-lint-js-generate-error-documentation program, written in C++, reads .md files in docs/errors/, checks them for mistakes, then creates an .html file for the website. The .html file is checked into the repository. Checked-in generated code is difficult to maintain. Rewrite quick-lint-js-generate-error-documentation in JavaScript, integrating the .html generation with our website build pipeline. This means the .html file no longer needs to be checked into the repository.
1 parent da6817b commit 4cda7ac

File tree

8 files changed

+540
-594
lines changed

8 files changed

+540
-594
lines changed

‎.github/workflows/check-error-docs.yml

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -13,14 +13,23 @@ jobs:
1313
runs-on: ubuntu-18.04
1414
container: ghcr.io/quick-lint/quick-lint-js-github-builder:v1
1515
steps:
16+
- uses: mymindstorm/setup-emsdk@v7
17+
with:
18+
version: 2.0.4
1619
- uses: actions/checkout@v2
1720

18-
- name: configure
19-
run: CC=gcc-8 CXX=g++-8 cmake -DBUILD_TESTING=NO -S . -B build
20-
- name: build
21-
run: cmake --build build --config Debug
22-
- name: generate docs
23-
run: ./build/docs/quick-lint-js-generate-error-docs docs/errors/ website/public/errors/index.template.html website/public/errors/index.html
21+
- name: C++ configure
22+
run: emcmake cmake -S . -B build -G Ninja
23+
- name: C++ build
24+
run: emmake cmake --build build --target quick-lint-js-vscode quick-lint-js-vscode-licenses
25+
- name: C++ install
26+
run: emmake cmake --install build --component vscode --prefix wasm
27+
28+
- name: JS configure
29+
run: cd website && yarn install --production
30+
31+
- name: check
32+
run: node website/check-error-documentation.mjs
2433

2534
# quick-lint-js finds bugs in JavaScript programs.
2635
# Copyright (C) 2020 Matthew Glazar

‎website/check-error-documentation.mjs

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
// Copyright (C) 2020 Matthew Glazar
2+
// See end of file for extended copyright information.
3+
4+
import {
5+
documentationDirectoryPath,
6+
loadErrorDocumentationFilesAsync,
7+
reportProblemsInDocumentsAsync,
8+
} from "./src/error-documentation.mjs";
9+
10+
async function mainAsync() {
11+
let documents = await loadErrorDocumentationFilesAsync(
12+
documentationDirectoryPath
13+
);
14+
await reportProblemsInDocumentsAsync(documents);
15+
}
16+
17+
mainAsync().catch((error) => {
18+
console.error(error.stack);
19+
process.exit(1);
20+
});
21+
22+
// quick-lint-js finds bugs in JavaScript programs.
23+
// Copyright (C) 2020 Matthew Glazar
24+
//
25+
// This file is part of quick-lint-js.
26+
//
27+
// quick-lint-js is free software: you can redistribute it and/or modify
28+
// it under the terms of the GNU General Public License as published by
29+
// the Free Software Foundation, either version 3 of the License, or
30+
// (at your option) any later version.
31+
//
32+
// quick-lint-js is distributed in the hope that it will be useful,
33+
// but WITHOUT ANY WARRANTY; without even the implied warranty of
34+
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
35+
// GNU General Public License for more details.
36+
//
37+
// You should have received a copy of the GNU General Public License
38+
// along with quick-lint-js. If not, see <https://www.gnu.org/licenses/>.

‎website/package.json

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,10 @@
1212
"asciidoctor": "^2.2.4",
1313
"ejs": "^3.1.6",
1414
"express": "^4.17.1",
15+
"markdown-it": "^12.0.6",
1516
"mime": "^2.5.2",
16-
"morgan": "^1.10.0"
17+
"morgan": "^1.10.0",
18+
"quick-lint-js-wasm": "../wasm"
1719
},
1820
"devDependencies": {
1921
"axios": "^0.21.1",

‎website/public/errors/index.template.html renamed to ‎website/public/errors/index.ejs.html

Lines changed: 31 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,27 @@
11
<!DOCTYPE html>
22
<!-- Copyright (C) 2020 Matthew Glazar -->
33
<!-- See end of file for extended copyright information. -->
4-
<!-- ${generated_message} -->
54
<html>
65
<head>
6+
<script>
7+
//<%
8+
let url = await import("url");
9+
let moduleCacheBust = "#" + Date.now();
10+
11+
let {
12+
documentationDirectoryPath,
13+
loadErrorDocumentationFilesAsync,
14+
reportProblemsInDocumentsAsync,
15+
} = await import(
16+
url.pathToFileURL("../../src/error-documentation.mjs") + moduleCacheBust
17+
);
18+
19+
let documents = await loadErrorDocumentationFilesAsync(
20+
documentationDirectoryPath
21+
);
22+
await reportProblemsInDocumentsAsync(documents);
23+
//%>
24+
</script>
725
<title>quick-lint-js: errors and warnings</title>
826
<meta charset="utf-8" />
927
<meta
@@ -64,7 +82,18 @@ <h1><a href="../">quick-lint-js</a></h1>
6482
<p>
6583
quick-lint-js can find the following warnings and errors in your code:
6684
</p>
67-
${error_documentation}
85+
86+
<ul class="table-of-contents">
87+
<% for (let doc of documents) { %>
88+
<li>
89+
<a href="#<%= doc.titleErrorCode %>"
90+
><%= doc.titleErrorCode %>: <%= doc.titleErrorDescription %></a
91+
>
92+
</li>
93+
<% } %>
94+
</ul>
95+
96+
<% for (let doc of documents) { %> <%- doc.toHTML() %> <% } %>
6897
</main>
6998

7099
<footer>

0 commit comments

Comments
 (0)