refactor: migrate bin/api-docs to tools/api-docs as workspace `@wordpress/api-docs-generator` by USERSATOSHI · Pull Request #77019 · WordPress/gutenberg

USERSATOSHI · 2026-04-03T07:11:59Z

What?

Why?

The issue provides more context, but in short, this PR ensures the workspace package does not rely on root dependencies once dependency isolation is enforced.

How?

This PR converts the bin/api-docs into a new workspace @wordpress/api-docs-generator while still relating the functionality.

Testing Instructions

run all docs:* scripts in the root package.json

…pace

github-actions · 2026-04-03T10:42:36Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: USERSATOSHI <tusharbharti@git.wordpress.org>
Co-authored-by: manzoorwanijk <manzoorwanijk@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

Copilot

Pull request overview

This PR migrates the API docs generator from bin/api-docs into a dedicated workspace package at tools/api-docs (@wordpress/api-docs-generator) to make dependencies explicit and avoid relying on root-level devDependencies as workspace isolation tightens.

Changes:

Adds a new workspace package (tools/api-docs) with its own package.json and tsconfig.json.
Updates root package.json docs scripts to run via the new workspace and registers tools/api-docs in the workspaces list.
Refactors/extends API docs generation scripts (API ref, blocks, components, theme ref) to work from the new location.

Reviewed changes

Copilot reviewed 9 out of 13 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tools/api-docs/update-api-docs.js	Refactors docgen invocation and formatting step for the new workspace location.
tools/api-docs/tsconfig.json	Adds workspace-local TS config extending the repo base config.
tools/api-docs/package.json	Introduces the new private workspace package and its tool dependencies/scripts.
tools/api-docs/gen-theme-reference.mjs	Adds explicit lint suppression for `console.error` on failure path.
tools/api-docs/gen-components-docs/markdown/props.mjs	Adds markdown generation for component props sections.
tools/api-docs/gen-components-docs/markdown/index.mjs	Adds markdown document assembly via `json2md`.
tools/api-docs/gen-components-docs/index.mjs	Updates component-doc generation paths to be workspace-root aware.
tools/api-docs/gen-components-docs/get-tags-from-storybook.mjs	Updates Babel parsing configuration and anchors parsing to repo root.
tools/api-docs/gen-components-docs/get-subcomponent-descriptions.mjs	Updates Babel parsing configuration and anchors parsing to repo root.
tools/api-docs/gen-block-lib-list.js	Adds core block docs generation script under the new workspace.
tools/api-docs/are-api-docs-unstaged.js	Minor refactor/reorder of imports while moving script to new location.
package.json	Points `docs:*` scripts to the new workspace and adds `tools/api-docs` to workspaces.
package-lock.json	Updates lockfile for the new workspace package and dependency relocation.

Comments suppressed due to low confidence (1)

tools/api-docs/update-api-docs.js:243

execa(join(__dirname, '..', '..', 'node_modules', '.bin', 'docgen'), …) executes the unix shim directly. On Windows the executable is typically docgen.cmd, so this path may fail now that shell: true was removed. Prefer invoking docgen via execa('docgen', …, { cwd: ROOT_DIR, preferLocal: true }) or npm exec docgen … so npm resolves the correct platform-specific binary.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

manzoorwanijk

Apart from what Copilot suggested. I have some additional suggestions and questions.

manzoorwanijk · 2026-04-07T06:59:38Z

Since there is no TS file in this workspace, do we need this config and its reference in the root tsconfig?

#72973 - Many of these tools can later be converted to TypeScript when we use Node v24 with native type stripping

I was following the Storybook setup and thought we could keep it as-is, since it will likely be refactored to TypeScript later.

When that happens, we can add a tsconfig file but right now it’s unused.

This is not addressed yet. Let us delete this file for now.

manzoorwanijk · 2026-04-07T07:06:28Z

+		"url": "https://github.com/WordPress/gutenberg/issues"
+	},
+	"dependencies": {
+		"chalk": "4.1.1",


I noticed that we have multiple versions of chalk in the repo, which we can fix in a follow-up. Here, let us use the caret range.

Suggested change

"chalk": "4.1.1",

"chalk": "^4.1.1",

manzoorwanijk · 2026-04-07T07:06:41Z

+	},
+	"dependencies": {
+		"chalk": "4.1.1",
+		"execa": "4.0.2",


Suggested change

"execa": "4.0.2",

"execa": "^4.0.2",

manzoorwanijk · 2026-04-07T07:07:29Z

+		"@apidevtools/json-schema-ref-parser": "11.6.4",
+		"@babel/core": "7.25.7",


Suggested change

"@apidevtools/json-schema-ref-parser": "11.6.4",

"@babel/core": "7.25.7",

"@apidevtools/json-schema-ref-parser": "^11.6.4",

"@babel/core": "^7.25.7",

manzoorwanijk · 2026-04-07T07:08:06Z

+		"glob": "7.1.2",
+		"json2md": "2.0.1",
+		"react-docgen-typescript": "2.2.2"


Suggested change

"glob": "7.1.2",

"json2md": "2.0.1",

"react-docgen-typescript": "2.2.2"

"glob": "^7.1.2",

"json2md": "^2.0.1",

"react-docgen-typescript": "^2.2.2"

manzoorwanijk · 2026-04-07T07:08:57Z

+		sourceType: 'module',
+		cwd: ROOT_DIR,
+		rootMode: 'upward-optional',
+		parserOpts: {
+			sourceType: 'module',
+			plugins: [ 'jsx', 'typescript' ],
+		},


cwd makes sense, but why didn't we need the other options before? Do we need them now?

Ah, earlier, before discovering the rootMode option, I added these settings to fix Babel annotation errors caused by missing config resolution.

After rootMode resolved the issue, I forgot to remove them and reused them elsewhere.

manzoorwanijk · 2026-04-07T07:13:56Z

Thank you for working on this though.

This file will be added later when typescript migration is needed

…pace

manzoorwanijk

Thank you for working on this. It looks good now.

mirka · 2026-04-09T17:44:26Z

Did this need to be updated too? I think the commit hooks are failing because of this.

gutenberg/package.json

Line 247 in 5acfe09

"node ./bin/api-docs/are-api-docs-unstaged.js"

USERSATOSHI added 5 commits April 2, 2026 19:46

refactor: migrate bin/api-docs to tools/api-docs as workspace

7eca0fe

Merge branch 'WordPress:trunk' into try/migrate-api-docs-to-npm-works…

03c7374

…pace

chore: adding back the shell option to execa

53d9469

fix: removed the shell option to fix ci error

5837ff2

chore: npm install to fix dep issues

4cf9fb5

USERSATOSHI marked this pull request as ready for review April 3, 2026 10:42

USERSATOSHI requested review from ajitbohra, nerrad and ntwb as code owners April 3, 2026 10:42

manzoorwanijk added the [Type] Code Quality Issues or PRs that relate to code quality label Apr 7, 2026

manzoorwanijk requested a review from Copilot April 7, 2026 07:00

Copilot started reviewing on behalf of manzoorwanijk April 7, 2026 07:01 View session

Copilot AI reviewed Apr 7, 2026

View reviewed changes

Comment thread package.json Outdated

Comment thread package.json Outdated

manzoorwanijk requested changes Apr 7, 2026

View reviewed changes

manzoorwanijk mentioned this pull request Apr 7, 2026

Idea: Clean up root package.json and convert tools and tests to workspace packages #75041

Open

88 tasks

USERSATOSHI added 3 commits April 7, 2026 14:56

fix: update API docs scripts and dependencies for consistency

9b817fa

chore: fix dep order

fdd1032

chore: some ci test fixes

bf5014a

USERSATOSHI requested a review from manzoorwanijk April 9, 2026 07:38

chore: remove tsconfig.json for now

18b4bde

This file will be added later when typescript migration is needed

manzoorwanijk reviewed Apr 9, 2026

View reviewed changes

Comment thread package.json

Merge branch 'WordPress:trunk' into try/migrate-api-docs-to-npm-works…

b387247

…pace

manzoorwanijk approved these changes Apr 9, 2026

View reviewed changes

manzoorwanijk merged commit 2f07ef4 into WordPress:trunk Apr 9, 2026
40 checks passed

github-actions bot added this to the Gutenberg 23.0 milestone Apr 9, 2026

mirka mentioned this pull request Apr 9, 2026

Fix lint-staged API docs path #77203

Merged

		"@apidevtools/json-schema-ref-parser": "11.6.4",
		"@babel/core": "7.25.7",

Conversation

USERSATOSHI commented Apr 3, 2026

What?

Why?

How?

Testing Instructions

Uh oh!

github-actions bot commented Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

manzoorwanijk left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

manzoorwanijk commented Apr 7, 2026

Uh oh!

Uh oh!

manzoorwanijk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mirka commented Apr 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions bot commented Apr 3, 2026 •

edited

Loading