From b4aafb9e418b1dfad86b821fcf51c22052ec15bc Mon Sep 17 00:00:00 2001 From: Yuta Saito Date: Thu, 5 Sep 2024 08:57:01 +0000 Subject: [PATCH] Use typedoc to generate API documentation --- .github/workflows/docs.yml | 4 +- package-lock.json | 180 ++++++++++++-- package.json | 3 +- .../npm-packages/ruby-wasm-wasi/README.md | 233 +----------------- rakelib/doc.rake | 24 +- 5 files changed, 179 insertions(+), 265 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 61822e7fbf..42ff502e47 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -29,8 +29,8 @@ jobs: - name: Setup Pages id: pages uses: actions/configure-pages@v5 - - name: Build HTML by RDoc - run: rake rdoc + - name: Build HTML + run: rake doc - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: diff --git a/package-lock.json b/package-lock.json index ea1ac142f8..0c747e19d4 100644 --- a/package-lock.json +++ b/package-lock.json @@ -12,7 +12,8 @@ "@bytecodealliance/jco": "1.4.4", "@playwright/test": "^1.46.1", "@rollup/plugin-json": "^6.1.0", - "rollup": "^4.21.2" + "rollup": "^4.21.2", + "typedoc": "^0.26.6" } }, "node_modules/@ampproject/remapping": { @@ -319,21 +320,6 @@ "url": "https://github.com/sponsors/isaacs" } }, - "node_modules/@rollup/plugin-commonjs/node_modules/minimatch": { - "version": "9.0.4", - "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.4.tgz", - "integrity": "sha512-KqWh+VchfxcMNRAJjj2tnsSJdNbHsVgnkBhTNrW7AjVo6OvLtxw8zfT9oLw1JSohlFzJ8jCoTgaoXvJ+kHt6fw==", - "dev": true, - "dependencies": { - "brace-expansion": "^2.0.1" - }, - "engines": { - "node": ">=16 || 14 >=14.17" - }, - "funding": { - "url": "https://github.com/sponsors/isaacs" - } - }, "node_modules/@rollup/plugin-json": { "version": "6.1.0", "resolved": "https://registry.npmjs.org/@rollup/plugin-json/-/plugin-json-6.1.0.tgz", @@ -477,12 +463,37 @@ "resolved": "packages/npm-packages/ruby-wasm-wasi", "link": true }, + "node_modules/@shikijs/core": { + "version": "1.16.2", + "resolved": "https://registry.npmjs.org/@shikijs/core/-/core-1.16.2.tgz", + "integrity": "sha512-XSVH5OZCvE4WLMgdoBqfPMYmGHGmCC3OgZhw0S7KcSi2XKZ+5oHGe71GFnTljgdOxvxx5WrRks6QoTLKrl1eAA==", + "dev": true, + "dependencies": { + "@shikijs/vscode-textmate": "^9.2.0", + "@types/hast": "^3.0.4" + } + }, + "node_modules/@shikijs/vscode-textmate": { + "version": "9.2.0", + "resolved": "https://registry.npmjs.org/@shikijs/vscode-textmate/-/vscode-textmate-9.2.0.tgz", + "integrity": "sha512-5FinaOp6Vdh/dl4/yaOTh0ZeKch+rYS8DUb38V3GMKYVkdqzxw53lViRKUYkVILRiVQT7dcPC7VvAKOR73zVtQ==", + "dev": true + }, "node_modules/@types/estree": { "version": "1.0.5", "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.5.tgz", "integrity": "sha512-/kYRxGDLWzHOB7q+wtSUQlFrtcdUccpfy+X+9iMBpHK8QLLhx2wIPYuS5DYtR9Wa/YlZAbIovy7qVdB1Aq6Lyw==", "dev": true }, + "node_modules/@types/hast": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/@types/hast/-/hast-3.0.4.tgz", + "integrity": "sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==", + "dev": true, + "dependencies": { + "@types/unist": "*" + } + }, "node_modules/@types/node": { "version": "20.12.2", "resolved": "https://registry.npmjs.org/@types/node/-/node-20.12.2.tgz", @@ -497,6 +508,12 @@ "dev": true, "license": "MIT" }, + "node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "dev": true + }, "node_modules/@vitest/expect": { "version": "2.0.5", "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-2.0.5.tgz", @@ -608,6 +625,12 @@ "node": ">=8" } }, + "node_modules/argparse": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", + "dev": true + }, "node_modules/assertion-error": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz", @@ -827,6 +850,18 @@ "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==", "dev": true }, + "node_modules/entities": { + "version": "4.5.0", + "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz", + "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==", + "dev": true, + "engines": { + "node": ">=0.12" + }, + "funding": { + "url": "https://github.com/fb55/entities?sponsor=1" + } + }, "node_modules/esbuild": { "version": "0.21.5", "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.21.5.tgz", @@ -1030,6 +1065,15 @@ "@pkgjs/parseargs": "^0.11.0" } }, + "node_modules/linkify-it": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-5.0.0.tgz", + "integrity": "sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==", + "dev": true, + "dependencies": { + "uc.micro": "^2.0.0" + } + }, "node_modules/log-symbols": { "version": "6.0.0", "resolved": "https://registry.npmjs.org/log-symbols/-/log-symbols-6.0.0.tgz", @@ -1088,6 +1132,12 @@ "node": "14 || >=16.14" } }, + "node_modules/lunr": { + "version": "2.3.9", + "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz", + "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==", + "dev": true + }, "node_modules/magic-string": { "version": "0.30.11", "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.11.tgz", @@ -1097,6 +1147,29 @@ "@jridgewell/sourcemap-codec": "^1.5.0" } }, + "node_modules/markdown-it": { + "version": "14.1.0", + "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-14.1.0.tgz", + "integrity": "sha512-a54IwgWPaeBCAAsv13YgmALOF1elABB08FxO9i+r4VFk5Vl4pKokRPeX8u5TCgSsPi6ec1otfLjdOpVcgbpshg==", + "dev": true, + "dependencies": { + "argparse": "^2.0.1", + "entities": "^4.4.0", + "linkify-it": "^5.0.0", + "mdurl": "^2.0.0", + "punycode.js": "^2.3.1", + "uc.micro": "^2.1.0" + }, + "bin": { + "markdown-it": "bin/markdown-it.mjs" + } + }, + "node_modules/mdurl": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-2.0.0.tgz", + "integrity": "sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==", + "dev": true + }, "node_modules/merge-stream": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/merge-stream/-/merge-stream-2.0.0.tgz", @@ -1112,6 +1185,21 @@ "node": ">=6" } }, + "node_modules/minimatch": { + "version": "9.0.5", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.5.tgz", + "integrity": "sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow==", + "dev": true, + "dependencies": { + "brace-expansion": "^2.0.1" + }, + "engines": { + "node": ">=16 || 14 >=14.17" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, "node_modules/minipass": { "version": "7.1.2", "resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.2.tgz", @@ -1395,6 +1483,15 @@ "url": "https://github.com/prettier/prettier?sponsor=1" } }, + "node_modules/punycode.js": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/punycode.js/-/punycode.js-2.3.1.tgz", + "integrity": "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==", + "dev": true, + "engines": { + "node": ">=6" + } + }, "node_modules/resolve": { "version": "1.22.2", "dev": true, @@ -1483,6 +1580,17 @@ "node": ">=8" } }, + "node_modules/shiki": { + "version": "1.16.2", + "resolved": "https://registry.npmjs.org/shiki/-/shiki-1.16.2.tgz", + "integrity": "sha512-gSym0hZf5a1U0iDPsdoOAZbvoi+e0c6c3NKAi03FoSLTm7oG20tum29+gk0wzzivOasn3loxfGUPT+jZXIUbWg==", + "dev": true, + "dependencies": { + "@shikijs/core": "1.16.2", + "@shikijs/vscode-textmate": "^9.2.0", + "@types/hast": "^3.0.4" + } + }, "node_modules/siginfo": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz", @@ -1674,6 +1782,28 @@ "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.7.0.tgz", "integrity": "sha512-gLXCKdN1/j47AiHiOkJN69hJmcbGTHI0ImLmbYLHykhgeN0jVGola9yVjFgzCUklsZQMW55o+dW7IXv3RCXDzA==" }, + "node_modules/typedoc": { + "version": "0.26.6", + "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.26.6.tgz", + "integrity": "sha512-SfEU3SH3wHNaxhFPjaZE2kNl/NFtLNW5c1oHsg7mti7GjmUj1Roq6osBQeMd+F4kL0BoRBBr8gQAuqBlfFu8LA==", + "dev": true, + "dependencies": { + "lunr": "^2.3.9", + "markdown-it": "^14.1.0", + "minimatch": "^9.0.5", + "shiki": "^1.9.1", + "yaml": "^2.4.5" + }, + "bin": { + "typedoc": "bin/typedoc" + }, + "engines": { + "node": ">= 18" + }, + "peerDependencies": { + "typescript": "4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x || 5.5.x" + } + }, "node_modules/typescript": { "version": "5.5.4", "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.5.4.tgz", @@ -1687,6 +1817,12 @@ "node": ">=14.17" } }, + "node_modules/uc.micro": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-2.1.0.tgz", + "integrity": "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==", + "dev": true + }, "node_modules/undici-types": { "version": "5.26.5", "dev": true, @@ -2031,6 +2167,18 @@ "url": "https://github.com/chalk/ansi-styles?sponsor=1" } }, + "node_modules/yaml": { + "version": "2.5.1", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.5.1.tgz", + "integrity": "sha512-bLQOjaX/ADgQ20isPJRvF0iRUHIxVhYvr53Of7wGcWlO2jvtUlH5m87DsmulFVxRpNLOnI4tB6p/oh8D7kpn9Q==", + "dev": true, + "bin": { + "yaml": "bin.mjs" + }, + "engines": { + "node": ">= 14" + } + }, "packages/npm-packages/ruby-3.2-wasm-wasi": { "name": "@ruby/3.2-wasm-wasi", "version": "2.6.2", diff --git a/package.json b/package.json index 076899115b..9e74860e6b 100644 --- a/package.json +++ b/package.json @@ -8,6 +8,7 @@ "@bytecodealliance/jco": "1.4.4", "@playwright/test": "^1.46.1", "@rollup/plugin-json": "^6.1.0", - "rollup": "^4.21.2" + "rollup": "^4.21.2", + "typedoc": "^0.26.6" } } diff --git a/packages/npm-packages/ruby-wasm-wasi/README.md b/packages/npm-packages/ruby-wasm-wasi/README.md index ff270e6b45..99a06ae275 100644 --- a/packages/npm-packages/ruby-wasm-wasi/README.md +++ b/packages/npm-packages/ruby-wasm-wasi/README.md @@ -16,235 +16,4 @@ See [Cheat Sheet](https://github.com/ruby/ruby.wasm/blob/main/docs/cheat_sheet.m ## API - - -### consolePrinter - -Create a console printer that can be used as an overlay of WASI imports. -See the example below for how to use it. - -```javascript -const imports = { - wasi_snapshot_preview1: wasi.wasiImport, -}; -const printer = consolePrinter(); -printer.addToImports(imports); - -const instance = await WebAssembly.instantiate(module, imports); -printer.setMemory(instance.exports.memory); -``` - -Note that the `stdout` and `stderr` functions are called with text, not -bytes. This means that bytes written to stdout/stderr will be decoded as -UTF-8 and then passed to the `stdout`/`stderr` functions every time a write -occurs without buffering. - -#### Parameters - -- `$0` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** (optional, default `{stdout:console.log,stderr:console.warn}`) - - - `$0.stdout` - - `$0.stderr` - -- `stdout` A function that will be called when stdout is written to. - Defaults to `console.log`. -- `stderr` A function that will be called when stderr is written to. - Defaults to `console.warn`. - -Returns **any** An object that can be used as an overlay of WASI imports. - -### RubyVM - -A Ruby VM instance - -#### Examples - -```javascript -const wasi = new WASI(); -const vm = new RubyVM(); -const imports = { - wasi_snapshot_preview1: wasi.wasiImport, -}; - -vm.addToImports(imports); - -const instance = await WebAssembly.instantiate(rubyModule, imports); -await vm.setInstance(instance); -wasi.initialize(instance); -vm.initialize(); -``` - -#### initialize - -Initialize the Ruby VM with the given command line arguments - -##### Parameters - -- `args` The command line arguments to pass to Ruby. Must be - an array of strings starting with the Ruby program name. (optional, default `["ruby.wasm","-EUTF-8","-e_=0"]`) - -#### setInstance - -Set a given instance to interact JavaScript and Ruby's -WebAssembly instance. This method must be called before calling -Ruby API. - -##### Parameters - -- `instance` The WebAssembly instance to interact with. Must - be instantiated from a Ruby built with JS extension, and built - with Reactor ABI instead of command line. - -#### addToImports - -Add intrinsic import entries, which is necessary to interact JavaScript -and Ruby's WebAssembly instance. - -##### Parameters - -- `imports` The import object to add to the WebAssembly instance - -#### printVersion - -Print the Ruby version to stdout - -#### eval - -Runs a string of Ruby code from JavaScript - -##### Parameters - -- `code` The Ruby code to run - -##### Examples - -```javascript -vm.eval("puts 'hello world'"); -const result = vm.eval("1 + 2"); -console.log(result.toString()); // 3 -``` - -Returns **any** the result of the last expression - -#### evalAsync - -Runs a string of Ruby code with top-level `JS::Object#await` -Returns a promise that resolves when execution completes. - -##### Parameters - -- `code` The Ruby code to run - -##### Examples - -```javascript -const text = await vm.evalAsync(` - require 'js' - response = JS.global.fetch('https://example.com').await - response.text.await -`); -console.log(text.toString()); // ... -``` - -Returns **any** a promise that resolves to the result of the last expression - -#### wrap - -Wrap a JavaScript value into a Ruby JS::Object - -##### Parameters - -- `value` The value to convert to RbValue - -##### Examples - -```javascript -const hash = vm.eval(`Hash.new`); -hash.call("store", vm.eval(`"key1"`), vm.wrap(new Object())); -``` - -Returns **any** the RbValue object representing the given JS value - -### RbValue - -A RbValue is an object that represents a value in Ruby - -#### call - -Call a given method with given arguments - -##### Parameters - -- `callee` name of the Ruby method to call -- `args` **...any** arguments to pass to the method. Must be an array of RbValue - -##### Examples - -```javascript -const ary = vm.eval("[1, 2, 3]"); -ary.call("push", vm.wrap(4)); -console.log(ary.call("sample").toString()); -``` - -Returns **any** The result of the method call as a new RbValue. - -#### callAsync - -Call a given method that may call `JS::Object#await` with given arguments - -##### Parameters - -- `callee` name of the Ruby method to call -- `args` **...any** arguments to pass to the method. Must be an array of RbValue - -##### Examples - -```javascript -const client = vm.eval(` - require 'js' - class HttpClient - def get(url) - JS.global.fetch(url).await - end - end - HttpClient.new -`); -const response = await client.callAsync( - "get", - vm.eval(`"https://example.com"`), -); -``` - -Returns **any** A Promise that resolves to the result of the method call as a new RbValue. - -#### toPrimitive - -- **See**: - -##### Parameters - -- `hint` Preferred type of the result primitive value. `"number"`, `"string"`, or `"default"`. - -#### toString - -Returns a string representation of the value by calling `to_s` - -#### toJS - -Returns a JavaScript object representation of the value -by calling `to_js`. - -Returns null if the value is not convertible to a JavaScript object. - -### RbError - -**Extends Error** - -Error class thrown by Ruby execution - -### RbFatalError - -**Extends RbError** - -Error class thrown by Ruby execution when it is not possible to recover. -This is usually caused when Ruby VM is in an inconsistent state. +See [API Documentation](https://ruby.github.io/ruby.wasm/npm/@ruby/ruby-wasm-wasi) for details. diff --git a/rakelib/doc.rake b/rakelib/doc.rake index 8fe7e41472..d405fb478e 100644 --- a/rakelib/doc.rake +++ b/rakelib/doc.rake @@ -12,18 +12,14 @@ RDoc::Task.new do |doc| ] end -namespace :doc do - desc "Update docs/api/javascript.md" - task :api_js do - sh "npx", - "documentation", - "readme", - "--readme-file", - "./packages/npm-packages/ruby-wasm-wasi/README.md", - "--section", - "API", - "--markdown-toc", - "false", - "./packages/npm-packages/ruby-wasm-wasi/dist/esm/index.js" - end +desc "Generate TypeScript documentation" +task :typedoc do + mkdir_p "html/npm/@ruby/wasm-wasi" + sh "npx typedoc packages/npm-packages/ruby-wasm-wasi/src/index.ts --sort source-order --out html/npm/@ruby/wasm-wasi" +end + +desc "Generate documentation site" +task :doc do + Rake::Task["rdoc"].invoke + Rake::Task["typedoc"].invoke end