Skip to content

Commit 37e9855

Browse files
turadgturadg
committed
build: generate docs
1 parent 81c6349 commit 37e9855

File tree

19 files changed

+186
-7
lines changed

19 files changed

+186
-7
lines changed

‎.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,7 @@ bundles
5656
bundle-*.js
5757
compiled
5858
dist
59+
api-docs
5960

6061
# misc
6162
/.vagrant

‎docs/typescript.md

+10
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,13 @@ So our best solution is to have one source of truth for the types and auto-gener
1212
- `src/types.d.ts` is built automatically from types-ambient
1313
- `prepack` copies types-ambient.js to types.js and appends 'export {};' to turn it into a module, then builds
1414
- `postpack` deletes the new types.js and .d.ts files
15+
16+
## Generating API docs
17+
18+
We use [TypeDoc](https://typedoc.org/) to render API docs in HTML.
19+
20+
```sh
21+
yarn docs
22+
open api-docs/index.html
23+
```
24+

‎package.json

+2
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@
3333
"prettier": "^3.0.3",
3434
"prettier-plugin-jsdoc": "^1.0.0",
3535
"type-coverage": "^2.26.3",
36+
"typedoc": "^0.25.4",
3637
"typescript": "~5.2.2"
3738
},
3839
"engines": {
@@ -64,6 +65,7 @@
6465
"scripts": {
6566
"clean": "yarn lerna run --no-bail clean",
6667
"check-dependencies": "node ./scripts/check-mismatched-dependencies.cjs",
68+
"docs": "typedoc --tsconfig tsconfig.build.json",
6769
"lerna": "lerna",
6870
"link-cli": "yarn run create-agoric-cli",
6971
"create-agoric-cli": "node ./scripts/create-agoric-cli.cjs",

‎packages/ERTP/typedoc.json

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"extends": [
3+
"../../typedoc.base.json"
4+
],
5+
"entryPoints": [
6+
"src/index.js"
7+
],
8+
"validation": {
9+
"notExported": false,
10+
"invalidLink": false,
11+
}
12+
}

‎packages/assert/typedoc.json

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"extends": [
3+
"../../typedoc.base.json"
4+
],
5+
"entryPoints": [
6+
"src/assert.js",
7+
"src/types.js",
8+
]
9+
}

‎packages/governance/typedoc.json

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"extends": [
3+
"../../typedoc.base.json"
4+
],
5+
"entryPoints": [
6+
"src/index.js",
7+
// FIXME hitting errors like: Failed to find JSDoc tag for ParamValueTyped after parsing comment, please file a bug report.
8+
// "src/types-ambient.js",
9+
"tools/puppetGovernance.js",
10+
]
11+
}

‎packages/inter-protocol/typedoc.json

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"extends": [
3+
"../../typedoc.base.json"
4+
],
5+
"entryPoints": [
6+
"src/index.js",
7+
"src/clientSupport.js",
8+
]
9+
}

‎packages/notifier/typedoc.json

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"extends": [
3+
"../../typedoc.base.json"
4+
],
5+
"entryPoints": [
6+
"src/index.js",
7+
]
8+
}

‎packages/store/src/types.js

+4-2
Original file line numberDiff line numberDiff line change
@@ -132,7 +132,8 @@
132132
// ///////////////////////// Deprecated Legacy /////////////////////////////////
133133

134134
/**
135-
* @template K,V
135+
* @template K
136+
* @template V
136137
* @typedef {object} LegacyWeakMap LegacyWeakMap is deprecated. Use WeakMapStore
137138
* instead if possible.
138139
* @property {(key: K) => boolean} has Check if a key exists
@@ -145,7 +146,8 @@
145146
*/
146147

147148
/**
148-
* @template K,V
149+
* @template K
150+
* @template V
149151
* @typedef {object} LegacyMap LegacyMap is deprecated. Use MapStore instead if
150152
* possible.
151153
* @property {(key: K) => boolean} has Check if a key exists

‎packages/store/typedoc.json

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"extends": [
3+
"../../typedoc.base.json"
4+
],
5+
"entryPoints": [
6+
"src/index.js",
7+
"src/types.js"
8+
]
9+
}

‎packages/swingset-liveslots/README.md

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# SwingSet Liveslots
2+

‎packages/swingset-liveslots/typedoc.json

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"extends": [
3+
"../../typedoc.base.json"
4+
],
5+
"entryPoints": [
6+
"src/index.js",
7+
"src/types.js",
8+
"src/vatDataTypes.js",
9+
]
10+
}

‎packages/time/typedoc.json

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"extends": [
3+
"../../typedoc.base.json"
4+
],
5+
"entryPoints": [
6+
"src/timeMath.js",
7+
"src/types.js"
8+
]
9+
}

‎packages/vat-data/typedoc.json

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"extends": [
3+
"../../typedoc.base.json"
4+
],
5+
"entryPoints": [
6+
"src/index.js",
7+
]
8+
}

‎packages/zoe/typedoc.json

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{
2+
"extends": [
3+
"../../typedoc.base.json"
4+
],
5+
"entryPoints": [
6+
"src/contractSupport/index.js",
7+
"src/contractSupport/types.js",
8+
"src/contractFacet/types-ambient.d.ts",
9+
"src/contractFacet/types.ts",
10+
"src/zoeService/types.js",
11+
"src/zoeService/utils.d.ts",
12+
"src/zoeService/zoe.js",
13+
"src/types.js",
14+
"tools/manualTimer.js",
15+
]
16+
}

‎tsconfig.json

+2-3
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,16 @@
44
"module": "esnext",
55
"moduleResolution": "node",
66
"skipLibCheck": true,
7-
87
"allowJs": true,
98
"checkJs": true,
109
"strict": false,
1110
"downlevelIteration": true,
1211
"strictNullChecks": true,
1312
"noImplicitThis": true,
14-
1513
"noEmit": true
1614
},
1715
"include": [
18-
".eslintrc.cjs"
16+
".eslintrc.cjs",
17+
"dist"
1918
]
2019
}

‎typedoc.base.json

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"$schema": "https://typedoc.org/schema.json",
3+
"includeVersion": true
4+
}

‎typedoc.json

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"entryPoints": [
3+
"packages/*"
4+
],
5+
"exclude": [
6+
"packages/cosmic-proto/"
7+
],
8+
"name": "API documentation of Agoric SDK ",
9+
"entryPointStrategy": "packages",
10+
"out": "api-docs",
11+
"includeVersion": true,
12+
"logLevel": "Verbose"
13+
}

‎yarn.lock

+47-2
Original file line numberDiff line numberDiff line change
@@ -2633,6 +2633,11 @@ ansi-regex@^6.0.1:
26332633
resolved "https://registry.yarnpkg.com/ansi-regex/-/ansi-regex-6.0.1.tgz#3183e38fae9a65d7cb5e53945cd5897d0260a06a"
26342634
integrity sha512-n5M855fKb2SsfMIiFFoVrABHJC8QtHwVx+mHWP3QcEqBHYienj5dHSgjbxtC0WEZXYt4wcD6zrQElDPhFuZgfA==
26352635

2636+
ansi-sequence-parser@^1.1.0:
2637+
version "1.1.1"
2638+
resolved "https://registry.yarnpkg.com/ansi-sequence-parser/-/ansi-sequence-parser-1.1.1.tgz#e0aa1cdcbc8f8bb0b5bca625aac41f5f056973cf"
2639+
integrity sha512-vJXt3yiaUL4UU546s3rPXlsry/RnM730G1+HkpKE012AN0sx1eOrxSu95oKDIonskeLTijMgqWZ3uDEe3NFvyg==
2640+
26362641
ansi-styles@^3.2.1:
26372642
version "3.2.1"
26382643
resolved "https://registry.yarnpkg.com/ansi-styles/-/ansi-styles-3.2.1.tgz#41fbb20243e50b12be0f04b8dedbf07520ce841d"
@@ -6136,7 +6141,7 @@ json5@^2.2.2:
61366141
resolved "https://registry.yarnpkg.com/json5/-/json5-2.2.3.tgz#78cd6f1a19bdc12b73db5ad0c61efd66c1e29283"
61376142
integrity sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==
61386143

6139-
[email protected]:
6144+
[email protected], jsonc-parser@^3.2.0:
61406145
version "3.2.0"
61416146
resolved "https://registry.yarnpkg.com/jsonc-parser/-/jsonc-parser-3.2.0.tgz#31ff3f4c2b9793f89c67212627c51c6394f88e76"
61426147
integrity sha512-gfFQZrcTc8CnKXp6Y4/CBT3fTc0OVuDofpre4aEeEpSBPV5X5v4+Vmx+8snU7RLPrNHPKSgLxGo9YuQzz20o+w==
@@ -6458,6 +6463,11 @@ lru-cache@^7.14.0, lru-cache@^7.4.4, lru-cache@^7.5.1, lru-cache@^7.7.1:
64586463
resolved "https://registry.yarnpkg.com/lru-cache/-/lru-cache-10.0.0.tgz#b9e2a6a72a129d81ab317202d93c7691df727e61"
64596464
integrity sha512-svTf/fzsKHffP42sujkO/Rjs37BCIsQVRCeNYIm9WN8rgT7ffoUnRtZCqU+6BqcSBdv8gwJeTz8knJpgACeQMw==
64606465

6466+
lunr@^2.3.9:
6467+
version "2.3.9"
6468+
resolved "https://registry.yarnpkg.com/lunr/-/lunr-2.3.9.tgz#18b123142832337dd6e964df1a5a7707b25d35e1"
6469+
integrity sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==
6470+
64616471
magic-string@^0.25.7:
64626472
version "0.25.7"
64636473
resolved "https://registry.yarnpkg.com/magic-string/-/magic-string-0.25.7.tgz#3f497d6fd34c669c6798dcb821f2ef31f5445051"
@@ -6540,6 +6550,11 @@ map-obj@^4.0.0:
65406550
resolved "https://registry.yarnpkg.com/map-obj/-/map-obj-4.3.0.tgz#9304f906e93faae70880da102a9f1df0ea8bb05a"
65416551
integrity sha512-hdN1wVrZbb29eBGiGjJbeP8JbKjq1urkHJ/LIP/NY48MZ1QVXUsQBV1G1zvYFHn1XE06cwjBsOI2K3Ulnj1YXQ==
65426552

6553+
marked@^4.3.0:
6554+
version "4.3.0"
6555+
resolved "https://registry.yarnpkg.com/marked/-/marked-4.3.0.tgz#796362821b019f734054582038b116481b456cf3"
6556+
integrity sha512-PRsaiG84bK+AMvxziE/lCFss8juXjNaWzVbN5tXAm4XjeaS9NAHhop+PjQxz2A9h8Q4M/xGmzP8vqNwy6JeK0A==
6557+
65436558
matcher@^5.0.0:
65446559
version "5.0.0"
65456560
resolved "https://registry.yarnpkg.com/matcher/-/matcher-5.0.0.tgz#cd82f1c7ae7ee472a9eeaf8ec7cac45e0fe0da62"
@@ -6921,7 +6936,7 @@ [email protected]:
69216936
dependencies:
69226937
brace-expansion "^1.1.7"
69236938

6924-
"minimatch@6 || 7 || 8 || 9", minimatch@^9.0.1:
6939+
"minimatch@6 || 7 || 8 || 9", minimatch@^9.0.1, minimatch@^9.0.3:
69256940
version "9.0.3"
69266941
resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-9.0.3.tgz#a6e00c3de44c3a542bfaae70abfc22420a6da825"
69276942
integrity sha512-RHiac9mvaRw0x3AYRgDC1CxAP7HTcNrrECeA8YYJeWnpo+2Q5CegtZjaotWTWxDG3UeGA1coE05iH1mPjT/2mg==
@@ -8698,6 +8713,16 @@ shell-quote@^1.6.1:
86988713
resolved "https://registry.yarnpkg.com/shell-quote/-/shell-quote-1.7.3.tgz#aa40edac170445b9a431e17bb62c0b881b9c4123"
86998714
integrity sha512-Vpfqwm4EnqGdlsBFNmHhxhElJYrdfcxPThu+ryKS5J8L/fhAwLazFZtq+S+TWZ9ANj2piSQLGj6NQg+lKPmxrw==
87008715

8716+
shiki@^0.14.1:
8717+
version "0.14.5"
8718+
resolved "https://registry.yarnpkg.com/shiki/-/shiki-0.14.5.tgz#375dd214e57eccb04f0daf35a32aa615861deb93"
8719+
integrity sha512-1gCAYOcmCFONmErGTrS1fjzJLA7MGZmKzrBNX7apqSwhyITJg2O102uFzXUeBxNnEkDA9vHIKLyeKq0V083vIw==
8720+
dependencies:
8721+
ansi-sequence-parser "^1.1.0"
8722+
jsonc-parser "^3.2.0"
8723+
vscode-oniguruma "^1.7.0"
8724+
vscode-textmate "^8.0.0"
8725+
87018726
side-channel@^1.0.4:
87028727
version "1.0.4"
87038728
resolved "https://registry.yarnpkg.com/side-channel/-/side-channel-1.0.4.tgz#efce5c8fdc104ee751b25c58d4290011fa5ea2cf"
@@ -9448,6 +9473,16 @@ typedarray@^0.0.6:
94489473
resolved "https://registry.yarnpkg.com/typedarray/-/typedarray-0.0.6.tgz#867ac74e3864187b1d3d47d996a78ec5c8830777"
94499474
integrity sha1-hnrHTjhkGHsdPUfZlqeOxciDB3c=
94509475

9476+
typedoc@^0.25.4:
9477+
version "0.25.4"
9478+
resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.25.4.tgz#5c2c0677881f504e41985f29d9aef0dbdb6f1e6f"
9479+
integrity sha512-Du9ImmpBCw54bX275yJrxPVnjdIyJO/84co0/L9mwe0R3G4FSR6rQ09AlXVRvZEGMUg09+z/usc8mgygQ1aidA==
9480+
dependencies:
9481+
lunr "^2.3.9"
9482+
marked "^4.3.0"
9483+
minimatch "^9.0.3"
9484+
shiki "^0.14.1"
9485+
94519486
"typescript@^3 || ^4":
94529487
version "4.9.5"
94539488
resolved "https://registry.yarnpkg.com/typescript/-/typescript-4.9.5.tgz#095979f9bcc0d09da324d58d03ce8f8374cbe65a"
@@ -9617,6 +9652,16 @@ vary@~1.1.2:
96179652
resolved "https://registry.yarnpkg.com/vary/-/vary-1.1.2.tgz#2299f02c6ded30d4a5961b0b9f74524a18f634fc"
96189653
integrity sha1-IpnwLG3tMNSllhsLn3RSShj2NPw=
96199654

9655+
vscode-oniguruma@^1.7.0:
9656+
version "1.7.0"
9657+
resolved "https://registry.yarnpkg.com/vscode-oniguruma/-/vscode-oniguruma-1.7.0.tgz#439bfad8fe71abd7798338d1cd3dc53a8beea94b"
9658+
integrity sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA==
9659+
9660+
vscode-textmate@^8.0.0:
9661+
version "8.0.0"
9662+
resolved "https://registry.yarnpkg.com/vscode-textmate/-/vscode-textmate-8.0.0.tgz#2c7a3b1163ef0441097e0b5d6389cd5504b59e5d"
9663+
integrity sha512-AFbieoL7a5LMqcnOF04ji+rpXadgOXnZsxQr//r83kLPr7biP7am3g9zbaZIaBGwBRWeSvoMD4mgPdX3e4NWBg==
9664+
96209665
walk-up-path@^1.0.0:
96219666
version "1.0.0"
96229667
resolved "https://registry.yarnpkg.com/walk-up-path/-/walk-up-path-1.0.0.tgz#d4745e893dd5fd0dbb58dd0a4c6a33d9c9fec53e"

0 commit comments

Comments
 (0)