Offline, privacy-first grammar checker. Fast, open-source, Rust-powered
docs(harper.js): setup automatic API documentation generation
Elijah Potter19e36a29e686
diff --git a/Dockerfile b/Dockerfileindex 56919cb89..f757fcef1 100644--- a/Dockerfile+++ b/Dockerfile@@ -12,7 +12,7 @@ RUN wasm-pack build --release --target webFROM node:slim AS node-build-RUN apt-get update && apt-get install git -y+RUN apt-get update && apt-get install git pandoc -yRUN 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.shWORKDIR /usr/build/packages/webdiff --git a/justfile b/justfileindex d2416ecb5..43d975885 100644--- a/justfile+++ b/justfile@@ -13,12 +13,16 @@ build-harperjs:set -eo pipefailjust 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 -fyarn run build+ # Generate API reference+ ./build.sh+test-harperjs:#!/bin/bashset -eo pipefail@@ -40,6 +44,7 @@ dev-web:set -eo pipefailjust build-harperjs+ scd "{{justfile_directory()}}/packages/web"yarn install -fdiff --git a/packages/harper.js/.gitignore b/packages/harper.js/.gitignoreindex a547bf36d..9c821f794 100644--- a/packages/harper.js/.gitignore+++ b/packages/harper.js/.gitignore@@ -22,3 +22,6 @@ dist-ssr*.njsproj*.sln*.sw?++markdown+tempdiff --git a/packages/harper.js/api-extractor.json b/packages/harper.js/api-extractor.jsonnew file mode 100644index 000000000..9f9fbc444--- /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.shnew file mode 100755index 000000000..488b30e55--- /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 '<link rel="stylesheet" href="https://unpkg.com/mvp.css">' >> 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/refdiff --git a/packages/harper.js/package.json b/packages/harper.js/package.jsonindex 29bc0a1ce..af16b6311 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.tsindex 8f9031e0c..6402e6be6 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.tsindex 7f175d6ef..b043b11d3 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<string, boolean | undefined>;diff --git a/packages/harper.js/vite.config.js b/packages/harper.js/vite.config.jsindex 7988ca445..f23b88f49 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/.gitignoreindex c773de3e9..383426730 100644--- a/packages/web/.gitignore+++ b/packages/web/.gitignore@@ -9,3 +9,5 @@ node_modules!.env.examplevite.config.js.timestamp-*vite.config.ts.timestamp-*++static/docs/harperjs/refdiff --git a/packages/web/src/routes/docs/contributors/environment/+page.md b/packages/web/src/routes/docs/contributors/environment/+page.mdindex 3d0ee5e0e..d87cd8c86 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.tsindex 4ad00314d..e5ffc9862 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.lockindex f58072907..e7c373ede 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/[email protected]":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==+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"