diff --git a/Dockerfile b/Dockerfile
index 56919cb8..f757fcef 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -12,7 +12,7 @@ RUN wasm-pack build --release --target web
FROM node:slim AS node-build
-RUN apt-get update && apt-get install git -y
+RUN apt-get update && apt-get install git pandoc -y
RUN mkdir -p /usr/build/
WORKDIR /usr/build/
@@ -25,7 +25,7 @@ COPY demo.md .
WORKDIR /usr/build/packages/harper.js
-RUN yarn install && yarn build
+RUN yarn install && yarn build && ./docs.sh
WORKDIR /usr/build/packages/web
diff --git a/justfile b/justfile
index d2416ecb..43d97588 100644
--- a/justfile
+++ b/justfile
@@ -13,12 +13,16 @@ build-harperjs:
set -eo pipefail
just build-wasm web
+ # Removes a duplicate copy of the WASM binary if Vite is left to its devices.
sed -i 's/new URL(.*)/new URL()/g' "{{justfile_directory()}}/harper-wasm/pkg/harper_wasm.js"
-
+
cd "{{justfile_directory()}}/packages/harper.js"
yarn install -f
yarn run build
+ # Generate API reference
+ ./build.sh
+
test-harperjs:
#!/bin/bash
set -eo pipefail
@@ -40,6 +44,7 @@ dev-web:
set -eo pipefail
just build-harperjs
+ s
cd "{{justfile_directory()}}/packages/web"
yarn install -f
diff --git a/packages/harper.js/.gitignore b/packages/harper.js/.gitignore
index a547bf36..9c821f79 100644
--- a/packages/harper.js/.gitignore
+++ b/packages/harper.js/.gitignore
@@ -22,3 +22,6 @@ dist-ssr
*.njsproj
*.sln
*.sw?
+
+markdown
+temp
diff --git a/packages/harper.js/api-extractor.json b/packages/harper.js/api-extractor.json
new file mode 100644
index 00000000..9f9fbc44
--- /dev/null
+++ b/packages/harper.js/api-extractor.json
@@ -0,0 +1,20 @@
+{
+ "mainEntryPointFilePath": "./dist/harper.d.ts",
+ "apiReport": {
+ "enabled": false
+ },
+ "docModel": {
+ "enabled": true
+ },
+ "dtsRollup": {
+ "enabled": false
+ },
+ "bundledPackages": ["wasm"],
+ "messages": {
+ "extractorMessageReporting": {
+ "ae-missing-release-tag": {
+ "logLevel": "none"
+ }
+ }
+ }
+}
diff --git a/packages/harper.js/docs.sh b/packages/harper.js/docs.sh
new file mode 100755
index 00000000..488b30e5
--- /dev/null
+++ b/packages/harper.js/docs.sh
@@ -0,0 +1,24 @@
+#! /bin/bash
+
+set -eo pipefail
+
+yarn run api-extractor run
+yarn run api-documenter markdown -i temp
+
+rm -r html || true
+mkdir html || true
+
+echo Rendering HTML...
+
+for file in ./markdown/*.md
+do
+ BASE=$(basename $file .md)
+ pandoc $file -o html/$BASE.html
+ sed -i 's/"\(.*\).md"/"\1.html"/g' html/$BASE.html
+
+ echo '' >> html/$BASE.html
+done
+
+rm -r ../web/static/docs/harperjs || true
+mkdir -p ../web/static/docs/harperjs || true
+mv -f html ../web/static/docs/harperjs/ref
diff --git a/packages/harper.js/package.json b/packages/harper.js/package.json
index 29bc0a1c..af16b631 100644
--- a/packages/harper.js/package.json
+++ b/packages/harper.js/package.json
@@ -20,14 +20,16 @@
"test": "vitest run --browser chromium && vitest run --browser firefox"
},
"devDependencies": {
- "wasm": "link:../../harper-wasm/pkg",
+ "@microsoft/api-documenter": "^7.26.5",
+ "@microsoft/api-extractor": "^7.49.1",
"@vitest/browser": "^2.1.8",
"playwright": "^1.49.1",
"typescript": "~5.6.2",
"vite": "^5.1.8",
"vite-plugin-dts": "^4.5.0",
"vite-plugin-virtual": "^0.3.0",
- "vitest": "^2.1.8"
+ "vitest": "^2.1.8",
+ "wasm": "link:../../harper-wasm/pkg"
},
"main": "dist/harper.js",
"types": "dist/harper.d.ts"
diff --git a/packages/harper.js/src/LocalLinter.ts b/packages/harper.js/src/LocalLinter.ts
index 8f9031e0..6402e6be 100644
--- a/packages/harper.js/src/LocalLinter.ts
+++ b/packages/harper.js/src/LocalLinter.ts
@@ -3,7 +3,7 @@ import Linter from './Linter';
import loadWasm from './loadWasm';
import { LintConfig } from './main';
-/** A Linter that runs in the current JavaScript context (meaning it is allowed to block the event loop). */
+/** A Linter that runs in the current JavaScript context (meaning it is allowed to block the event loop). */
export default class LocalLinter implements Linter {
private inner: WasmLinter | undefined;
diff --git a/packages/harper.js/src/main.ts b/packages/harper.js/src/main.ts
index 7f175d6e..b043b11d 100644
--- a/packages/harper.js/src/main.ts
+++ b/packages/harper.js/src/main.ts
@@ -6,5 +6,4 @@ import WorkerLinter from './WorkerLinter';
export { LocalLinter, WorkerLinter, SuggestionKind };
export type { Linter, Lint, Span, Suggestion };
-
export type LintConfig = Record;
diff --git a/packages/harper.js/vite.config.js b/packages/harper.js/vite.config.js
index 7988ca44..f23b88f4 100644
--- a/packages/harper.js/vite.config.js
+++ b/packages/harper.js/vite.config.js
@@ -2,6 +2,12 @@ import { resolve } from 'path';
import dts from 'vite-plugin-dts';
import { defineConfig } from 'vite';
import virtual from 'vite-plugin-virtual';
+import fs from 'fs';
+
+function fileAsObject(path) {
+ let content = fs.readFileSync(path);
+ return JSON.parse(content);
+}
export default defineConfig({
build: {
@@ -19,7 +25,11 @@ export default defineConfig({
},
base: './',
plugins: [
- dts({ rollupTypes: true, tsconfigPath: './tsconfig.json', bundledPackages: ['wasm'] }),
+ dts({
+ ...fileAsObject('./api-extractor.json'),
+ rollupTypes: true,
+ tsconfigPath: './tsconfig.json'
+ }),
virtual({
'virtual:wasm': `import wasmUri from 'wasm/harper_wasm_bg.wasm?inline'; export default wasmUri`
})
diff --git a/packages/web/.gitignore b/packages/web/.gitignore
index c773de3e..38342673 100644
--- a/packages/web/.gitignore
+++ b/packages/web/.gitignore
@@ -9,3 +9,5 @@ node_modules
!.env.example
vite.config.js.timestamp-*
vite.config.ts.timestamp-*
+
+static/docs/harperjs/ref
diff --git a/packages/web/src/routes/docs/contributors/environment/+page.md b/packages/web/src/routes/docs/contributors/environment/+page.md
index 3d0ee5e0..d87cd8c8 100644
--- a/packages/web/src/routes/docs/contributors/environment/+page.md
+++ b/packages/web/src/routes/docs/contributors/environment/+page.md
@@ -12,6 +12,7 @@ To use the tooling required to build and debug Harper, you'll need to the follow
- `grep`
- [`wasm-pack`](https://rustwasm.github.io/wasm-pack/installer/)
- `zip`
+- `pandoc`
We develop a set of tools, accessible via `just`, to build and debug Harper's algorithm (otherwise known as `harper-core`) and its various integrations.
To get see all the tools in your toolbox run:
diff --git a/packages/web/vite.config.ts b/packages/web/vite.config.ts
index 4ad00314..e5ffc986 100644
--- a/packages/web/vite.config.ts
+++ b/packages/web/vite.config.ts
@@ -87,6 +87,10 @@ export default defineConfig({
{
title: 'CDN',
to: '/docs/harperjs/CDN'
+ },
+ {
+ title: 'API Reference',
+ to: '/docs/harperjs/ref/index.html'
}
]
},
diff --git a/packages/yarn.lock b/packages/yarn.lock
index f5807290..e7c373ed 100644
--- a/packages/yarn.lock
+++ b/packages/yarn.lock
@@ -1814,6 +1814,19 @@
resolved "https://registry.yarnpkg.com/@lukeed/csprng/-/csprng-1.1.0.tgz#1e3e4bd05c1cc7a0b2ddbd8a03f39f6e4b5e6cfe"
integrity sha512-Z7C/xXCiGWsg0KuKsHTKJxbWhpI3Vs5GwLfOean7MGyVFGqdRgBbAjOCh6u4bbjPc/8MJ2pZmK/0DLdCbivLDA==
+"@microsoft/api-documenter@^7.26.5":
+ version "7.26.5"
+ resolved "https://registry.yarnpkg.com/@microsoft/api-documenter/-/api-documenter-7.26.5.tgz#8166910abfcc6cd514c57c9061dd484c1a19dcda"
+ integrity sha512-E1V8FIHd1ePefbvCZoQfusBPMyKqIq/VqgfJGeZKjOYluwQMlZEgJT18t0XH8zPMO5/rB/PWAVkv4fKrsnoYjw==
+ dependencies:
+ "@microsoft/api-extractor-model" "7.30.2"
+ "@microsoft/tsdoc" "~0.15.1"
+ "@rushstack/node-core-library" "5.10.2"
+ "@rushstack/terminal" "0.14.5"
+ "@rushstack/ts-command-line" "4.23.3"
+ js-yaml "~3.13.1"
+ resolve "~1.22.1"
+
"@microsoft/api-extractor-model@7.30.2":
version "7.30.2"
resolved "https://registry.yarnpkg.com/@microsoft/api-extractor-model/-/api-extractor-model-7.30.2.tgz#9c0b2446f6bbcdd0159e16b0e8f8694d645ce257"
@@ -3497,18 +3510,18 @@ arg@^5.0.2:
resolved "https://registry.yarnpkg.com/arg/-/arg-5.0.2.tgz#c81433cc427c92c4dcf4865142dbca6f15acd59c"
integrity sha512-PYjyFOLKQ9y57JvQ6QLo8dAgNqswh8M1RMJYdQduT6xbWSgK36P/Z/v+p888pM69jMMfS8Xd8F6I1kQ/I9HUGg==
-argparse@^2.0.1:
- version "2.0.1"
- resolved "https://registry.yarnpkg.com/argparse/-/argparse-2.0.1.tgz#246f50f3ca78a3240f6c997e8a9bd1eac49e4b38"
- integrity sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==
-
-argparse@~1.0.9:
+argparse@^1.0.7, argparse@~1.0.9:
version "1.0.10"
resolved "https://registry.yarnpkg.com/argparse/-/argparse-1.0.10.tgz#bcd6791ea5ae09725e17e5ad988134cd40b3d911"
integrity sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==
dependencies:
sprintf-js "~1.0.2"
+argparse@^2.0.1:
+ version "2.0.1"
+ resolved "https://registry.yarnpkg.com/argparse/-/argparse-2.0.1.tgz#246f50f3ca78a3240f6c997e8a9bd1eac49e4b38"
+ integrity sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==
+
aria-query@5.3.0:
version "5.3.0"
resolved "https://registry.yarnpkg.com/aria-query/-/aria-query-5.3.0.tgz#650c569e41ad90b51b3d7df5e5eed1c7549c103e"
@@ -4834,6 +4847,11 @@ espree@^9.6.0, espree@^9.6.1:
acorn-jsx "^5.3.2"
eslint-visitor-keys "^3.4.1"
+esprima@^4.0.0:
+ version "4.0.1"
+ resolved "https://registry.yarnpkg.com/esprima/-/esprima-4.0.1.tgz#13b04cdb3e6c5d19df91ab6987a8695619b0aa71"
+ integrity sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==
+
esquery@^1.4.2:
version "1.5.0"
resolved "https://registry.yarnpkg.com/esquery/-/esquery-1.5.0.tgz#6ce17738de8577694edd7361c57182ac8cb0db0b"
@@ -5978,6 +5996,14 @@ js-yaml@^4.1.0:
dependencies:
argparse "^2.0.1"
+js-yaml@~3.13.1:
+ version "3.13.1"
+ resolved "https://registry.yarnpkg.com/js-yaml/-/js-yaml-3.13.1.tgz#aff151b30bfdfa8e49e05da22e7415e9dfa37847"
+ integrity sha512-YfbcO7jXDdyj0DGxYVSlSeQNHbD7XPWvrVWeVUujrQEoZzWJIRrCPoyk6kL6IAjAG2IolMK4T0hNUe0HOUs5Jw==
+ dependencies:
+ argparse "^1.0.7"
+ esprima "^4.0.0"
+
jsesc@^3.0.2:
version "3.1.0"
resolved "https://registry.yarnpkg.com/jsesc/-/jsesc-3.1.0.tgz#74d335a234f67ed19907fdadfac7ccf9d409825d"