Skip to content

Commit

Permalink
docs(harper.js): setup automatic API documentation generation
Browse files Browse the repository at this point in the history
  • Loading branch information
elijah-potter committed Jan 13, 2025
1 parent aad7519 commit 19e36a2
Show file tree
Hide file tree
Showing 13 changed files with 110 additions and 14 deletions.
4 changes: 2 additions & 2 deletions Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -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/
Expand All @@ -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

Expand Down
7 changes: 6 additions & 1 deletion justfile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -40,6 +44,7 @@ dev-web:
set -eo pipefail

just build-harperjs
s

cd "{{justfile_directory()}}/packages/web"
yarn install -f
Expand Down
3 changes: 3 additions & 0 deletions packages/harper.js/.gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -22,3 +22,6 @@ dist-ssr
*.njsproj
*.sln
*.sw?

markdown
temp
20 changes: 20 additions & 0 deletions packages/harper.js/api-extractor.json
Original file line number Diff line number Diff line change
@@ -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"
}
}
}
}
24 changes: 24 additions & 0 deletions packages/harper.js/docs.sh
Original file line number Diff line number Diff line change
@@ -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/ref
6 changes: 4 additions & 2 deletions packages/harper.js/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
2 changes: 1 addition & 1 deletion packages/harper.js/src/LocalLinter.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down
1 change: 0 additions & 1 deletion packages/harper.js/src/main.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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>;
12 changes: 11 additions & 1 deletion packages/harper.js/vite.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -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: {
Expand All @@ -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`
})
Expand Down
2 changes: 2 additions & 0 deletions packages/web/.gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,5 @@ node_modules
!.env.example
vite.config.js.timestamp-*
vite.config.ts.timestamp-*

static/docs/harperjs/ref
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
4 changes: 4 additions & 0 deletions packages/web/vite.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,10 @@ export default defineConfig({
{
title: 'CDN',
to: '/docs/harperjs/CDN'
},
{
title: 'API Reference',
to: '/docs/harperjs/ref/index.html'
}
]
},
Expand Down
38 changes: 32 additions & 6 deletions packages/yarn.lock
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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"
Expand Down Expand Up @@ -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"
Expand Down Expand Up @@ -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"
Expand Down

0 comments on commit 19e36a2

Please sign in to comment.