Tools: migrate docs/tool into tools/docs workspace

.github/CODEOWNERS

@@ -55,7 +55,6 @@
 # Tooling
 /bin                                            @ntwb @nerrad @ajitbohra
 /bin/api-docs                                   @ntwb @nerrad @ajitbohra
-/docs/tool                                      @ajitbohra
 /packages/babel-plugin-import-jsx-pragma        @ntwb @nerrad @ajitbohra
 /packages/babel-plugin-makepot                  @ntwb @nerrad @ajitbohra
 /packages/babel-preset-default                  @ntwb @nerrad @ajitbohra

docs/contributors/folder-structure.md

@@ -59,18 +59,15 @@ The following snippet explains how the Gutenberg repository is structured omitti
     ├── .github/*
     │   Config of the different GitHub features (issues and PR templates, CI, owners).
     │
-    ├── tools/api-docs
-    │   Tool/script used to generate the API Docs.
+    ├── tools/docs
+    │   Tools for generating Gutenberg documentation (manifest generator, API docs, block library list, component docs, theme reference).
     │
     ├── tools/build-scripts
     │   Build orchestration scripts for the Gutenberg monorepo (@wordpress/build-scripts).
     │
     ├── tools/release
     │   CLI tool used to perform the Gutenberg plugin release and the npm releases as well.
     │
-    ├── docs/tool
-    │   Tool used to generate the Block editor handbook's markdown pages.
-    │
     ├── docs/*.md
     │   Set of documentation pages composing the [Block editor handbook](https://developer.wordpress.org/block-editor/).
     │

package.json

@@ -60,7 +60,6 @@
 		"babel-jest": "29.7.0",
 		"babel-loader": "9.2.1",
 		"babel-plugin-inline-json-import": "0.3.2",
-		"change-case": "4.1.2",
 		"concurrently": "3.5.0",
 		"cross-env": "7.0.3",
 		"css-loader": "^6.2.0",
@@ -104,13 +103,13 @@
 		"component-usage-stats": "node ./node_modules/react-scanner/bin/react-scanner -c ./react-scanner.config.js",
 		"dev": "npm run --workspace @wordpress/build-scripts dev --",
 		"distclean": "git clean --force -d -X",
-		"docs:api-ref": "npm run --workspace @wordpress/api-docs-generator docs:api-ref",
-		"docs:blocks": "npm run --workspace @wordpress/api-docs-generator docs:blocks",
+		"docs:api-ref": "npm run --workspace @wordpress/docs-tools docs:api-ref --",
+		"docs:blocks": "npm run --workspace @wordpress/docs-tools docs:blocks --",
 		"docs:build": "npm-run-all docs:components docs:gen docs:blocks docs:api-ref docs:theme-ref",
-		"docs:check-api-docs-unstaged": "node ./tools/api-docs/are-api-docs-unstaged.js",
-		"docs:components": "npm run --workspace @wordpress/api-docs-generator docs:components",
-		"docs:gen": "node ./docs/tool/index.js",
-		"docs:theme-ref": "npm run --workspace tools/api-docs docs:theme-ref",
+		"docs:check-api-docs-unstaged": "npm run --workspace @wordpress/docs-tools docs:check-api-docs-unstaged --",
+		"docs:components": "npm run --workspace @wordpress/docs-tools docs:components --",
+		"docs:gen": "npm run --workspace @wordpress/docs-tools docs:gen --",
+		"docs:theme-ref": "npm run --workspace @wordpress/docs-tools docs:theme-ref --",
 		"env": "wp-env",
 		"fixtures:clean": "rimraf --glob \"test/integration/fixtures/blocks/*.{json,serialized.html}\"",
 		"fixtures:generate": "cross-env GENERATE_MISSING_FIXTURES=y npm run test:unit -- test/integration/full-content/ && npm run format test/integration/fixtures/blocks/*.json",
@@ -205,14 +204,14 @@
 		"packages/*/package.json": [
 			"wp-scripts lint-pkg-json"
 		],
-		"{docs/{toc.json,tool/*.js},packages/{*/README.md,components/src/*/**/README.md}}": [
-			"node ./docs/tool/index.js"
+		"{docs/toc.json,tools/docs/*.cjs,packages/{*/README.md,components/src/*/**/README.md}}": [
+			"npm run docs:gen"
 		],
 		"packages/**/*.{js,ts,tsx,json}": [
 			"npm run docs:api-ref",
 			"npm run docs:blocks",
 			"npm run docs:theme-ref",
-			"node ./tools/api-docs/are-api-docs-unstaged.js"
+			"npm run docs:check-api-docs-unstaged"
 		],
 		"packages/icons/src/library/*": [
 			"npm run -w packages/icons build"

tools/api-docs/are-api-docs-unstaged.js → tools/docs/are-api-docs-unstaged.js

@@ -3,18 +3,22 @@
 /**
  * External dependencies
  */
-const { extname } = require( 'path' );
+const { extname, join, resolve } = require( 'path' );
 const { readFile } = require( 'fs' ).promises;
 const execSync = require( 'child_process' ).execSync;
 const chalk = require( 'chalk' );
 
+const ROOT_DIR = resolve( __dirname, '../..' );
+
 const getUnstagedFiles = () =>
-	execSync( 'git diff --name-only', { encoding: 'utf8' } )
+	execSync( 'git diff --name-only', { encoding: 'utf8', cwd: ROOT_DIR } )
 		.split( '\n' )
 		.filter( Boolean );
 
 const fileHasToken = async ( file ) =>
-	( await readFile( file, 'utf8' ) ).includes( '<!-- START TOKEN' );
+	( await readFile( join( ROOT_DIR, file ), 'utf8' ) ).includes(
+		'<!-- START TOKEN'
+	);
 
 const getUnstagedReadmes = () =>
 	Promise.all(

docs/tool/index.js → tools/docs/gen-manifest.cjs

@@ -7,10 +7,10 @@ const path = require( 'path' );
 /**
  * Internal dependencies
  */
-const { getRootManifest } = require( './manifest' );
+const { getRootManifest } = require( './manifest.cjs' );
 
-const tocFileInput = path.resolve( __dirname, '../toc.json' );
-const manifestOutput = path.resolve( __dirname, '../manifest.json' );
+const tocFileInput = path.resolve( __dirname, '../../docs/toc.json' );
+const manifestOutput = path.resolve( __dirname, '../../docs/manifest.json' );
 
 // Process TOC file and generate manifest handbook.
 fs.writeFileSync(

docs/tool/manifest.js → tools/docs/manifest.cjs

@@ -6,10 +6,12 @@
 const { pascalCase } = require( 'change-case' );
 const fs = require( 'fs' );
 const glob = require( 'glob' ).sync;
-const { join } = require( 'path' );
+const { join, resolve } = require( 'path' );
 
+const ROOT_DIR = resolve( __dirname, '../..' );
 const baseRepoUrl = '..';
 const componentPaths = glob( 'packages/components/src/*/**/README.md', {
+	cwd: ROOT_DIR,
 	// Don't expose documentation for mobile only and private components just yet.
 	ignore: [
 		'**/src/mobile/**/README.md',
@@ -21,11 +23,10 @@ const componentPaths = glob( 'packages/components/src/*/**/README.md', {
 		'packages/components/src/badge/README.md',
 	],
 } );
-const packagePaths = glob( 'packages/*/package.json' )
+const packagePaths = glob( 'packages/*/package.json', { cwd: ROOT_DIR } )
 	.filter(
 		// Ignore private packages.
-		( fileName ) =>
-			! require( join( __dirname, '..', '..', fileName ) ).private
+		( fileName ) => ! require( join( ROOT_DIR, fileName ) ).private
 	)
 	.map( ( fileName ) => fileName.split( '/' )[ 1 ] );
 
@@ -39,16 +40,8 @@ const packagePaths = glob( 'packages/*/package.json' )
 function getPackageManifest( packageFolderNames ) {
 	return packageFolderNames.reduce( ( manifest, folderName ) => {
 		const path = `${ baseRepoUrl }/packages/${ folderName }/README.md`;
-		const tocPath = `${ baseRepoUrl }/packages/${ folderName }/docs/toc.json`;
 		const packageJson = require(
-			join(
-				__dirname,
-				'..',
-				'..',
-				'packages',
-				folderName,
-				'package.json'
-			)
+			join( ROOT_DIR, 'packages', folderName, 'package.json' )
 		);
 
 		// First add any README files to the TOC
@@ -60,8 +53,15 @@ function getPackageManifest( packageFolderNames ) {
 		} );
 
 		// Next add any items in the docs/toc.json if found.
-		if ( fs.existsSync( join( __dirname, '..', tocPath ) ) ) {
-			const toc = require( join( __dirname, '..', tocPath ) ).values();
+		const tocFilePath = join(
+			ROOT_DIR,
+			'packages',
+			folderName,
+			'docs',
+			'toc.json'
+		);
+		if ( fs.existsSync( tocFilePath ) ) {
+			const toc = require( tocFilePath ).values();
 			manifest.push( ...toc );
 		}
 		return manifest;
@@ -112,7 +112,10 @@ function generateRootManifestFromTOCItems( items, parent = null ) {
 			}
 		}
 		let title = pascalCase( slug );
-		const markdownSource = fs.readFileSync( fileName, 'utf8' );
+		const markdownSource = fs.readFileSync(
+			join( ROOT_DIR, fileName ),
+			'utf8'
+		);
 		const titleMarkdown = markdownSource.match( /^#\s(.+)$/m );
 		if ( titleMarkdown ) {
 			title = titleMarkdown[ 1 ];

tools/api-docs/package.json → tools/docs/package.json

@@ -1,20 +1,20 @@
 {
-	"name": "@wordpress/api-docs-generator",
+	"name": "@wordpress/docs-tools",
 	"version": "0.0.0",
-	"description": "Tools for generating Gutenberg API documentation.",
+	"description": "Tools for generating Gutenberg documentation.",
 	"private": true,
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
 	"keywords": [
 		"wordpress",
 		"gutenberg",
-		"api-docs"
+		"docs"
 	],
-	"homepage": "https://github.com/WordPress/gutenberg/tree/HEAD/tools/api-docs",
+	"homepage": "https://github.com/WordPress/gutenberg/tree/HEAD/tools/docs",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/WordPress/gutenberg.git",
-		"directory": "tools/api-docs"
+		"directory": "tools/docs"
 	},
 	"bugs": {
 		"url": "https://github.com/WordPress/gutenberg/issues"
@@ -23,6 +23,7 @@
 		"@apidevtools/json-schema-ref-parser": "^11.6.4",
 		"@babel/core": "^7.25.7",
 		"chalk": "^4.1.1",
+		"change-case": "4.1.2",
 		"comment-parser": "^1.1.1",
 		"execa": "^4.0.2",
 		"fast-glob": "^3.2.7",
@@ -34,8 +35,10 @@
 		"access": "public"
 	},
 	"scripts": {
+		"docs:gen": "node ./gen-manifest.cjs",
 		"docs:api-ref": "node ./update-api-docs.js",
 		"docs:blocks": "node ./gen-block-lib-list.js",
+		"docs:check-api-docs-unstaged": "node ./are-api-docs-unstaged.js",
 		"docs:components": "node ./gen-components-docs/index.mjs",
 		"docs:theme-ref": "node ./gen-theme-reference.mjs"
 	}