diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index c8aebcf651..2a1338f9b9 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -94,6 +94,7 @@ /packages/eth-json-rpc-middleware @MetaMask/core-platform /packages/messenger @MetaMask/core-platform /packages/messenger-cli @MetaMask/core-platform +/packages/platform-api-docs @MetaMask/core-platform /packages/sample-controllers @MetaMask/core-platform /packages/polling-controller @MetaMask/core-platform /packages/preferences-controller @MetaMask/core-platform diff --git a/.github/workflows/deploy-platform-api-docs.yml b/.github/workflows/deploy-platform-api-docs.yml new file mode 100644 index 0000000000..127db9dee0 --- /dev/null +++ b/.github/workflows/deploy-platform-api-docs.yml @@ -0,0 +1,75 @@ +name: Deploy Platform API Docs + +on: + push: + branches: [main] + pull_request: + branches: [main] + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +permissions: + contents: read + +jobs: + build-docs: + name: Build Platform API docs + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - name: Checkout and setup environment + uses: MetaMask/action-checkout-and-setup@v3 + with: + is-high-risk-environment: false + + - name: Generate and build Platform API docs + run: yarn docs:platform-api:build + env: + DOCS_URL: https://${{ github.repository_owner }}.github.io + # The site is published under the `/platform-api/` subdirectory of + # the repo's GitHub Pages site so that other doc sites (e.g. + # package API docs) can be hosted alongside under sibling paths. + DOCS_BASE_URL: /${{ github.event.repository.name }}/platform-api/ + + - name: Upload build artifact (PR) + if: github.event_name == 'pull_request' + uses: actions/upload-artifact@v7 + with: + name: platform-api-docs + path: .platform-api-docs/build/ + retention-days: 7 + + - name: Upload build artifact for deploy job + if: github.ref == 'refs/heads/main' && github.event_name == 'push' + uses: actions/upload-artifact@v7 + with: + name: platform-api-docs-build + path: .platform-api-docs/build/ + retention-days: 1 + + deploy: + name: Deploy to GitHub Pages + if: github.ref == 'refs/heads/main' && github.event_name == 'push' + needs: build-docs + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - name: Download build artifact + uses: actions/download-artifact@v8 + with: + name: platform-api-docs-build + path: build/ + + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v4.1.0 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./build + destination_dir: platform-api + # Preserve sibling subdirectories (e.g. /package-api/) so this + # deploy only overwrites /platform-api/. + keep_files: true diff --git a/.gitignore b/.gitignore index 2f1de08239..448611d4ac 100644 --- a/.gitignore +++ b/.gitignore @@ -37,4 +37,7 @@ scripts/coverage packages/*/*.tsbuildinfo # AI -.sisyphus/ \ No newline at end of file +.sisyphus/ + +# Platform API docs (generated) +.platform-api-docs/ diff --git a/README.md b/README.md index 64a2300566..dab593c0bc 100644 --- a/README.md +++ b/README.md @@ -83,6 +83,7 @@ Each package in this repository has its own README where you can find installati - [`@metamask/permission-log-controller`](packages/permission-log-controller) - [`@metamask/perps-controller`](packages/perps-controller) - [`@metamask/phishing-controller`](packages/phishing-controller) +- [`@metamask/platform-api-docs`](packages/platform-api-docs) - [`@metamask/polling-controller`](packages/polling-controller) - [`@metamask/preferences-controller`](packages/preferences-controller) - [`@metamask/profile-metrics-controller`](packages/profile-metrics-controller) @@ -176,6 +177,7 @@ linkStyle default opacity:0.5 permission_log_controller(["@metamask/permission-log-controller"]); perps_controller(["@metamask/perps-controller"]); phishing_controller(["@metamask/phishing-controller"]); + platform_api_docs(["@metamask/platform-api-docs"]); polling_controller(["@metamask/polling-controller"]); preferences_controller(["@metamask/preferences-controller"]); profile_metrics_controller(["@metamask/profile-metrics-controller"]); diff --git a/eslint.config.mjs b/eslint.config.mjs index 85f596606b..cbd30d01d5 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -76,9 +76,11 @@ const config = createConfig([ '**/dist/**', '**/docs/**', '**/coverage/**', + '.platform-api-docs/**', 'merged-packages/**', '.yarn/**', 'scripts/create-package/package-template/**', + 'packages/platform-api-docs/site/**', ], }, { @@ -114,6 +116,7 @@ const config = createConfig([ '**/tests/**/*.{js,ts}', 'scripts/*.ts', 'scripts/create-package/**/*.ts', + 'packages/platform-api-docs/**/*.ts', ], extends: [nodejs], }, @@ -207,7 +210,7 @@ const config = createConfig([ }, }, { - files: ['scripts/*.ts'], + files: ['scripts/*.ts', 'packages/platform-api-docs/src/cli.ts'], rules: { // Scripts may be self-executable and thus have hashbangs. 'n/hashbang': 'off', @@ -306,6 +309,14 @@ const config = createConfig([ 'import-x/no-nodejs-modules': 'off', }, }, + { + files: ['packages/platform-api-docs/**/*.{js,ts}'], + rules: { + 'import-x/no-nodejs-modules': 'off', + 'n/no-process-env': 'off', + 'n/no-sync': 'off', + }, + }, { files: [ 'packages/notification-services-controller/src/NotificationServicesPushController/services/push/*-web.ts', diff --git a/package.json b/package.json index 35896187ef..fcc52b7583 100644 --- a/package.json +++ b/package.json @@ -22,6 +22,9 @@ "changelog:validate": "yarn workspaces foreach --all --no-private --parallel --interlaced --verbose run changelog:validate", "create-release-branch": "create-release-branch --formatter oxfmt", "create-package": "tsx scripts/create-package", + "docs:platform-api:build": "yarn workspace @metamask/platform-api-docs cli ../.. --build --project-label Core", + "docs:platform-api:dev": "yarn workspace @metamask/platform-api-docs cli ../.. --dev --project-label Core", + "docs:platform-api:serve": "yarn workspace @metamask/platform-api-docs cli ../.. --serve --project-label Core", "lint": "yarn lint:eslint && echo && yarn lint:misc --check && yarn constraints && yarn lint:dependencies && yarn lint:teams && yarn messenger-action-types:check && yarn readme-content:check", "lint:dependencies": "depcheck && yarn dedupe --check", "lint:dependencies:fix": "depcheck && yarn dedupe", @@ -96,7 +99,12 @@ }, "resolutions": { "elliptic@6.5.4": "^6.5.7", + "eslint-import-resolver-typescript": "3.7.0", + "eslint-plugin-import-x": "4.6.1", + "eslint-plugin-n": "17.15.1", "fast-xml-parser@^4.3.4": "^4.4.1", + "prettier@npm:^3.3.3": "3.4.2", + "webpackbar@^6.0.1": "^7.0.0", "ws@7.4.6": "^7.5.10" }, "simple-git-hooks": { @@ -111,9 +119,10 @@ "@lavamoat/preinstall-always-fail": false, "@keystonehq/bc-ur-registry-eth>hdkey>secp256k1": true, "babel-runtime>core-js": false, + "eslint-import-resolver-typescript>unrs-resolver": false, + "eslint-plugin-import-x>unrs-resolver": false, "simple-git-hooks": false, - "tsx>esbuild": false, - "eslint-plugin-import-x>unrs-resolver": false + "tsx>esbuild": false } } } diff --git a/packages/platform-api-docs/CHANGELOG.md b/packages/platform-api-docs/CHANGELOG.md new file mode 100644 index 0000000000..6ddb5e2f3d --- /dev/null +++ b/packages/platform-api-docs/CHANGELOG.md @@ -0,0 +1,14 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added + +- Initial release of the platform-api-docs package + +[Unreleased]: https://github.com/MetaMask/core/ diff --git a/packages/platform-api-docs/LICENSE b/packages/platform-api-docs/LICENSE new file mode 100644 index 0000000000..c259cd7ebc --- /dev/null +++ b/packages/platform-api-docs/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 MetaMask + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/packages/platform-api-docs/README.md b/packages/platform-api-docs/README.md new file mode 100644 index 0000000000..cd97e88ff3 --- /dev/null +++ b/packages/platform-api-docs/README.md @@ -0,0 +1,39 @@ +# `@metamask/platform-api-docs` + +Produces documentation for the platform API, the set of actions and events available in clients through the message bus. + +When run within a project (such as `metamask-extension` or `metamask-mobile`), this tool looks for messenger action and event types declared within TypeScript source and declaration files within MetaMask NPM packages. It extracts all of the JSDoc from these actions and events, then outputs them into a searchable Docusaurus site. + +## Installation + +1. Add this package as a dependency (`yarn add --dev @metamask/platform-api-docs` or `npm install --save-dev @metamask/platform-api-docs`). +2. Add a script to your project's `package.json`. For example: + ```json + { + "scripts": { + "docs:platform-api:build": "platform-api-docs --build --project-label MyProject" + } + } + ``` + +## Usage + +``` +platform-api-docs [project-path] [options] + +Arguments: + project-path Path to the project to scan (default: current directory) + +Options: + --build Generate docs and build static site + --serve Generate docs, build, and serve static site + --dev Generate docs and start dev server with hot reload + --scan-dir Extra source directory to scan (repeatable) + --output Output directory (default: /.platform-api-docs) + --project-label