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"