docs: Enable typedoc for snaps-sdk

.github/workflows/publish-main-docs.yml

@@ -0,0 +1,19 @@
+name: Publish main branch docs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  publish-to-gh-pages:
+    name: Publish docs to `staging` directory of `gh-pages` branch
+    permissions:
+      contents: write
+    uses: ./.github/workflows/publish-github-pages.yml
+    with:
+      build_script: yarn workspace @metamask/snaps-sdk build:docs
+      destination_dir: docs/staging
+      publish_dir: ./packages/snaps-sdk/docs
+    secrets:
+      PUBLISH_PAGES_TOKEN: ${{ secrets.PUBLISH_PAGES_TOKEN }}

.github/workflows/publish-release.yml

@@ -122,6 +122,47 @@ jobs:
           npm-token: ${{ secrets.NPM_TOKEN }}
           npm-tag: ${{ needs.get-release-tag.outputs.tag }}
 
+  get-sdk-release-version:
+    needs: npm-publish
+    runs-on: ubuntu-latest
+    outputs:
+      RELEASE_VERSION: ${{ steps.get-release-version.outputs.RELEASE_VERSION }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.sha }}
+      - id: get-release-version
+        shell: bash
+        run: |
+          RELEASE_VERSION="$(jq --raw-output '.version' packages/snaps-sdk/package.json)"
+          echo "RELEASE_VERSION=$RELEASE_VERSION" >> "$GITHUB_OUTPUT"
+
+  publish-release-to-gh-pages:
+    name: Publish docs to `docs/${{ needs.get-release-version.outputs.RELEASE_VERSION }}` directory of `gh-pages` branch
+    needs: get-sdk-release-version
+    permissions:
+      contents: write
+    uses: ./.github/workflows/publish-github-pages.yml
+    with:
+      build_script: yarn workspace @metamask/snaps-sdk build:docs
+      destination_dir: docs/${{ needs.get-sdk-release-version.outputs.RELEASE_VERSION }}
+      publish_dir: ./packages/snaps-sdk/docs
+    secrets:
+      PUBLISH_PAGES_TOKEN: ${{ secrets.PUBLISH_PAGES_TOKEN }}
+
+  publish-release-to-latest-gh-pages:
+    name: Publish docs to `latest` directory of `gh-pages` branch
+    needs: publish-release-to-gh-pages
+    permissions:
+      contents: write
+    uses: ./.github/workflows/publish-github-pages.yml
+    with:
+      build_script: yarn workspace @metamask/snaps-sdk build:docs
+      destination_dir: docs/latest
+      publish_dir: ./packages/snaps-sdk/docs
+    secrets:
+      PUBLISH_PAGES_TOKEN: ${{ secrets.PUBLISH_PAGES_TOKEN }}
+
   is-environment-release:
     name: Determine whether this release updates the iframe execution environment
     runs-on: ubuntu-latest

eslint.config.mjs

@@ -78,7 +78,15 @@ const config = createConfig([
       'jsdoc/check-tag-names': [
         'error',
         {
-          definedTags: ['property'],
+          definedTags: [
+            'property',
+
+            // Typedoc tags
+            'category',
+            'primaryExport',
+            'showCategories',
+            'showGroups',
+          ],
         },
       ],
 

packages/snaps-execution-environments/lavamoat/build-system/policy.json

@@ -433,7 +433,7 @@
     "html-webpack-plugin>pretty-error>renderkid>css-select>domutils>dom-serializer": {
       "packages": {
         "html-webpack-plugin>pretty-error>renderkid>htmlparser2>domelementtype": true,
-        "html-webpack-plugin>pretty-error>renderkid>htmlparser2>entities": true
+        "html-webpack-plugin>pretty-error>renderkid>css-select>domutils>dom-serializer>entities": true
       }
     },
     "html-webpack-plugin>pretty-error>renderkid>css-select>domhandler": {

packages/snaps-sdk/.depcheckrc.json

@@ -13,6 +13,7 @@
     "prettier-plugin-packagejson",
     "ts-node",
     "typedoc",
+    "typedoc-theme-fresh",
     "typescript"
   ]
 }

packages/snaps-sdk/.gitignore

@@ -0,0 +1 @@
+docs

packages/snaps-sdk/package.json

@@ -74,6 +74,7 @@
   ],
   "scripts": {
     "build": "ts-bridge --project tsconfig.build.json --verbose --clean --no-references",
+    "build:docs": "typedoc",
     "changelog:update": "../../scripts/update-changelog.sh @metamask/snaps-sdk",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/snaps-sdk",
     "lint": "yarn lint:eslint && yarn lint:misc --check && yarn changelog:validate && yarn lint:dependencies",
@@ -114,6 +115,8 @@
     "jest-silent-reporter": "^0.6.0",
     "prettier": "^3.3.3",
     "ts-jest": "^29.1.1",
+    "typedoc": "^0.28.16",
+    "typedoc-theme-fresh": "^0.2.3",
     "typescript": "~5.3.3"
   },
   "engines": {

packages/snaps-sdk/src/index.ts

@@ -1,3 +1,12 @@
+/**
+ * The main entry point for the Snaps SDK, which can be accessed by importing
+ * from `@metamask/snaps-sdk`.
+ *
+ * @module Main
+ * @primaryExport
+ * @showGroups
+ */
+
 // Only internals that are used by other Snaps packages should be exported here.
 export type { EnumToUnion } from './internals';
 export type { UriOptions } from './internals';

packages/snaps-sdk/src/jsx/components/Address.ts

@@ -10,6 +10,7 @@ import { createSnapComponent } from '../component';
  * @property truncate - Whether to truncate the address. Defaults to `true`.
  * @property displayName - Whether to show the account name. Defaults to `false`.
  * @property avatar - Whether to show the address avatar. Defaults to `true`.
+ * @category Component Props
  */
 export type AddressProps = {
   address: `0x${string}` | CaipAccountId;
@@ -42,12 +43,14 @@ const TYPE = 'Address';
  * <Address address="0x1234567890123456789012345678901234567890" truncate={false} avatar={false} />
  * @example
  * <Address address="0x1234567890123456789012345678901234567890" displayName={true} />
+ * @category Components
  */
 export const Address = createSnapComponent<AddressProps, typeof TYPE>(TYPE);
 
 /**
  * An address element.
  *
- * @see Address
+ * @see {@link Address}
+ * @category Elements
  */
 export type AddressElement = ReturnType<typeof Address>;

packages/snaps-sdk/src/jsx/components/Avatar.ts

@@ -7,6 +7,7 @@ import { createSnapComponent } from '../component';
  *
  * @property address - The address to display. This should be a valid CAIP-10 address.
  * @property size - The size of the avatar. Can be `sm`, `md`, or `lg`. Defaults to `md`.
+ * @category Component Props
  */
 export type AvatarProps = {
   address: CaipAccountId;
@@ -28,12 +29,14 @@ const TYPE = 'Avatar';
  * <Avatar address="eip155:1:0x1234567890123456789012345678901234567890" />
  * @example
  * <Avatar address="bip122:000000000019d6689c085ae165831e93:128Lkh3S7CkDTBZ8W7BbpsN3YYizJMp8p6" />
+ * @category Components
  */
 export const Avatar = createSnapComponent<AvatarProps, typeof TYPE>(TYPE);
 
 /**
  * An avatar element.
  *
- * @see Avatar
+ * @see {@link Avatar}
+ * @category Elements
  */
 export type AvatarElement = ReturnType<typeof Avatar>;

packages/snaps-sdk/src/jsx/components/Banner.ts

@@ -24,6 +24,7 @@ export type BannerChildren = SnapsChildren<
  * @param children - The content to display in the banner.
  * @param title - Title of the banner.
  * @param severity - Severity level of the banner.
+ * @category Component Props
  */
 export type BannerProps = {
   children: BannerChildren;
@@ -44,12 +45,14 @@ const TYPE = 'Banner';
  * <Banner title="Success banner" severity="success">
  *   <Text>Here is the banner content!</Text>
  * </Banner>
+ * @category Components
  */
 export const Banner = createSnapComponent<BannerProps, typeof TYPE>(TYPE);
 
 /**
  * A Banner element.
  *
- * @see Banner
+ * @see {@link Banner}
+ * @category Elements
  */
 export type BannerElement = ReturnType<typeof Banner>;

packages/snaps-sdk/src/jsx/components/Box.ts

@@ -9,6 +9,7 @@ import { createSnapComponent } from '../component';
  * @property alignment - The alignment mode to use within the box. Defaults to `start`.
  * @property crossAlignment - The cross alignment mode to use within the box.
  * @property center - Whether to center the children within the box. Defaults to `false`.
+ * @category Component Props
  */
 export type BoxProps = {
   // We can't use `JSXElement` because it causes a circular reference.
@@ -41,12 +42,14 @@ const TYPE = 'Box';
  * <Box>
  *   <Text>Hello world!</Text>
  * </Box>
+ * @category Components
  */
 export const Box = createSnapComponent<BoxProps, typeof TYPE>(TYPE);
 
 /**
  * A box element.
  *
- * @see Box
+ * @see {@link Box}
+ * @category Elements
  */
 export type BoxElement = ReturnType<typeof Box>;

packages/snaps-sdk/src/jsx/components/Card.ts

@@ -9,6 +9,7 @@ import { createSnapComponent } from '../component';
  * @property description - The description, shown below the title.
  * @property value - The value, shown on the right side.
  * @property extra - An additional optional value shown below the value.
+ * @category Component Props
  */
 export type CardProps = {
   image?: string | undefined;
@@ -32,12 +33,14 @@ const TYPE = 'Card';
  * @returns A card element.
  * @example
  * <Card image="<svg />" title="Title" description="Description" value="$1200" extra="0.12 ETH" />
+ * @category Components
  */
 export const Card = createSnapComponent<CardProps, typeof TYPE>(TYPE);
 
 /**
  * A card element.
  *
- * @see Card
+ * @see {@link Card}
+ * @category Elements
  */
 export type CardElement = ReturnType<typeof Card>;

packages/snaps-sdk/src/jsx/components/Container.ts

@@ -11,6 +11,7 @@ export type ContainerBackgroundColor = 'default' | 'alternative';
  * The props of the {@link Container} component.
  *
  * @property children - The Box and the Footer or the Box element.
+ * @category Component Props
  */
 export type ContainerProps = {
   children: [GenericSnapElement, FooterElement] | GenericSnapElement;
@@ -36,12 +37,14 @@ const TYPE = 'Container';
  *     <Button name="confirm">Confirm</Button>
  *   </Footer>
  * </Container>
+ * @category Components
  */
 export const Container = createSnapComponent<ContainerProps, typeof TYPE>(TYPE);
 
 /**
  * A container element.
  *
- * @see Container
+ * @see {@link Container}
+ * @category Elements
  */
 export type ContainerElement = ReturnType<typeof Container>;

packages/snaps-sdk/src/jsx/components/Copyable.ts

@@ -7,6 +7,7 @@ import { createSnapComponent } from '../component';
  * element.
  * @property sensitive - Whether the value is sensitive. If `true`, the value
  * will be hidden when the user is not interacting with the copyable element.
+ * @category Component Props
  */
 export type CopyableProps = {
   value: string;
@@ -27,12 +28,14 @@ const TYPE = 'Copyable';
  * @example
  * <Copyable value="0x1234567890123456789012345678901234567890" />
  * <Copyable value="0x1234567890123456789012345678901234567890" sensitive />
+ * @category Components
  */
 export const Copyable = createSnapComponent<CopyableProps, typeof TYPE>(TYPE);
 
 /**
  * A copyable element.
  *
- * @see Copyable
+ * @see {@link Copyable}
+ * @category Elements
  */
 export type CopyableElement = ReturnType<typeof Copyable>;

packages/snaps-sdk/src/jsx/components/Divider.ts

@@ -11,12 +11,14 @@ const TYPE = 'Divider';
  * @returns A divider element.
  * @example
  * <Divider />
+ * @category Components
  */
 export const Divider = createSnapComponent(TYPE);
 
 /**
  * A divider element.
  *
- * @see Divider
+ * @see {@link Divider}
+ * @category Elements
  */
 export type DividerElement = ReturnType<typeof Divider>;

packages/snaps-sdk/src/jsx/components/Footer.ts

@@ -5,6 +5,7 @@ import { createSnapComponent } from '../component';
  * The props of the {@link Footer} component.
  *
  * @property children - The single or multiple buttons in the footer.
+ * @category Component Props
  */
 export type FooterProps = {
   children: ButtonElement | [ButtonElement, ButtonElement];
@@ -23,12 +24,14 @@ const TYPE = 'Footer';
  *   <Button name="cancel">Cancel</Button>
  *   <Button name="confirm">Confirm</Button>
  * </Footer>
+ * @category Components
  */
 export const Footer = createSnapComponent<FooterProps, typeof TYPE>(TYPE);
 
 /**
  * A footer element.
  *
- * @see Footer
+ * @see {@link Footer}
+ * @category Elements
  */
 export type FooterElement = ReturnType<typeof Footer>;

packages/snaps-sdk/src/jsx/components/Heading.ts

@@ -6,6 +6,7 @@ import { createSnapComponent } from '../component';
  *
  * @property children - The text to display in the heading.
  * @property size - The size of the heading. Defaults to `sm`.
+ * @category Component Props
  */
 type HeadingProps = {
   children: StringElement;
@@ -25,12 +26,14 @@ const TYPE = 'Heading';
  * <Heading>Hello world!</Heading>
  * @example
  * <Heading size="lg">Hello world!</Heading>
+ * @category Components
  */
 export const Heading = createSnapComponent<HeadingProps, typeof TYPE>(TYPE);
 
 /**
  * A heading element.
  *
- * @see Heading
+ * @see {@link Heading}
+ * @category Elements
  */
 export type HeadingElement = ReturnType<typeof Heading>;