Automatically generate and publish API docs to GitHub Pages for each package once again
- 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