MetaMask / MetaMask/core

Automatically generate and publish API docs to GitHub Pages for each package once again

Open
#1,845 3 comments 0 reactions 0 assignees View on GitHub
category-documentation github-migration-triaged team-core-platform team-wallet-framework wf-documentation
Dominant language
TypeScript
Stars
413
Forks
308
Avg merge
1d 4h
Merged PRs (30d)
253

Description

h2. Problem

Currently, we do not publish generated API documentation to GitHub Pages for any of the packages in this monorepo. The workflow to do this was functional for a while, at least locally, but it broke when we switched over to {{ts-bridge}}. To be specific, {{typedoc}} now throws when run as it does not know what to do when there are type declaration files that do not end in {{.d.ts}} (ours end in {{d.cts}} and {{.d.mjs}}).

h2. Solution

To fix this, we need to fix the docs publishing workflow so that it clears out any existing built files, then re-builds the monorepo using {{tsc}} instead of {{ts-bridge}}. This will generate the {{.d.ts}} that {{typedoc}} expects. In addition, we need to configure {{typedoc}} at the package level so that it uses the build-specific TypeScript config file ({{tsconfig.build.json}}).

Finally, we need to update the docs publishing workflows to retain versions for deployments at the monorepo package level. We know that the URL must start with {{https://metamask.github.io/core}}, as that's how GitHub Pages works. We also need to account for the platform API docs, so we need to use {{https://metamask.github.io/core/packages}} as the prefix. However, each time we make a new release of a package, we don't want to blow away existing documentation for that package. So we need to determine which versions of packages are being released and assign them to the correct subdirectory. For instance, if a new release includes version 12.0.0 of {{keyring-controller}} and version 9.0.0 of {{base-controller}}, we would need to deploy the new documentation under {{https://metamask.github.io/core/packages/keyring-controller/v12.0.0}} and {{https://metamask.github.io/core/packages/base-controller/v9.0.0}}, respectively.

h2. Acceptance Criteria

* When a release PR is merged, a GitHub workflow runs that uses {{typedoc}} to generate documentation for all packages included in the release, copies each package's documentation to {{/}} in the {{gh-pages}} branch, and pushes that branch

* Visiting {{https://metamask.github.io/core/packages//}} should display the published documentation
* Visiting {{https://metamask.github.io/core/packages/}} should redirect to the documentation for the latest version of the package in question
* Visiting {{https://metamask.github.io/core/packages/}} should display a home page that allows navigating to the documentation for the latest version of each package in the monorepo

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by inspecting the docs-publishing GitHub workflows, package-level TypeDoc configuration, and tsconfig.build.json. Run the monorepo build with tsc before TypeDoc, then verify that the workflow identifies released package versions and writes them to the gh-pages branch. Done means versioned package URLs, latest-version redirects, and a navigable packages home page work as described.

Written by the indexing model from the issue text.

Assessment

Tech stack
github, github-actions, typescript
Domain
build-system, ci-cd, documentation, release
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
43/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.