Components: Set up README auto-generator

bin/api-docs/gen-components-docs/index.js

@@ -0,0 +1,72 @@
+/**
+ * External dependencies
+ */
+const docgen = require( 'react-docgen-typescript' );
+const glob = require( 'glob' );
+const fs = require( 'fs' );
+const path = require( 'path' );
+
+/**
+ * Internal dependencies
+ */
+const { generateMarkdownDocs } = require( './markdown' );
+
+// For consistency, options should generally match the options used in Storybook.
+const OPTIONS = {
+	shouldExtractLiteralValuesFromEnum: true,
+	shouldRemoveUndefinedFromOptional: true,
+	propFilter: ( prop ) =>
+		prop.parent ? ! /node_modules/.test( prop.parent.fileName ) : true,
+	savePropValueAsString: true,
+};
+
+function getTypeDocsForComponent( {
+	manifestPath,
+	componentFilePath,
+	displayName,
+} ) {
+	const resolvedPath = path.resolve(
+		path.dirname( manifestPath ),
+		componentFilePath
+	);
+
+	return docgen
+		.parse( resolvedPath, OPTIONS )
+		.find( ( obj ) => obj.displayName === displayName );
+}
+
+const manifests = glob.sync( 'packages/components/src/**/docs-manifest.json' );
+
+manifests.forEach( ( manifestPath ) => {
+	const manifest = JSON.parse( fs.readFileSync( manifestPath, 'utf8' ) );
+
+	const typeDocs = getTypeDocsForComponent( {
+		manifestPath,
+		componentFilePath: manifest.filePath,
+		displayName: manifest.displayName,
+	} );
+
+	const subcomponentTypeDocs = manifest.subcomponents?.map(
+		( subcomponent ) => {
+			const docs = getTypeDocsForComponent( {
+				manifestPath,
+				componentFilePath: subcomponent.filePath,
+				displayName: subcomponent.displayName,
+			} );
+
+			if ( subcomponent.preferredDisplayName ) {
+				docs.displayName = subcomponent.preferredDisplayName;
+			}
+
+			return docs;
+		}
+	);
+
+	const docs = generateMarkdownDocs( { typeDocs, subcomponentTypeDocs } );
+	const outputFile = path.resolve(
+		path.dirname( manifestPath ),
+		'./README.md'
+	);
+
+	fs.writeFileSync( outputFile, docs );
+} );

bin/api-docs/gen-components-docs/markdown/index.js

@@ -0,0 +1,44 @@
+/**
+ * External dependencies
+ */
+const json2md = require( 'json2md' );
+
+/**
+ * Internal dependencies
+ */
+const { generateMarkdownPropsJson } = require( './props' );
+
+function generateMarkdownDocs( { typeDocs, subcomponentTypeDocs } ) {
+	const mainDocsJson = [
+		'<!-- This file is generated automatically and cannot be edited directly. -->\n',
+		{ h1: typeDocs.displayName },
+		{
+			p: `<p class="callout callout-info">See the <a href="https://wordpress.github.io/gutenberg/?path=/docs/components-${ typeDocs.displayName.toLowerCase() }--docs">WordPress Storybook</a> for more detailed, interactive documentation.</p>`,
+		},
+		typeDocs.description,
+		...generateMarkdownPropsJson( typeDocs.props ),
+	];
+
+	const subcomponentDocsJson = subcomponentTypeDocs
+		? [
+				{ h2: 'Subcomponents' },
+				...subcomponentTypeDocs.flatMap( ( subcomponentTypeDoc ) => [
+					{
+						h3: subcomponentTypeDoc.displayName,
+					},
+					subcomponentTypeDoc.description,
+					...generateMarkdownPropsJson( subcomponentTypeDoc.props, {
+						headingLevel: 4,
+					} ),
+				] ),
+		  ]
+		: [];
+
+	return json2md(
+		[ ...mainDocsJson, ...subcomponentDocsJson ].filter( Boolean )
+	);
+}
+
+module.exports = {
+	generateMarkdownDocs,
+};

bin/api-docs/gen-components-docs/markdown/props.js

@@ -0,0 +1,53 @@
+function renderPropType( type ) {
+	switch ( type.name ) {
+		case 'enum': {
+			const MAX_ENUM_VALUES = 10;
+			const string = type.value
+				.slice( 0, MAX_ENUM_VALUES )
+				.map( ( { value } ) => value )
+				.join( ' | ' );
+
+			if ( type.value.length > MAX_ENUM_VALUES ) {
+				return `${ string } | ...`;
+			}
+			return string;
+		}
+		default:
+			return type.name;
+	}
+}
+
+function generateMarkdownPropsJson( props, { headingLevel = 2 } = {} ) {
+	const sortedKeys = Object.keys( props ).sort( ( [ a ], [ b ] ) =>
+		a.localeCompare( b )
+	);
+
+	const propsJson = sortedKeys
+		.flatMap( ( key ) => {
+			const prop = props[ key ];
+
+			if ( prop.description.includes( '@ignore' ) ) {
+				return null;
+			}
+
+			return [
+				{ [ `h${ headingLevel + 1 }` ]: `\`${ key }\`` },
+				prop.description,
+				{
+					ul: [
+						`Type: \`${ renderPropType( prop.type ) }\``,
+						`Required: ${ prop.required ? 'Yes' : 'No' }`,
+						prop.defaultValue &&
+							`Default: \`${ prop.defaultValue.value }\``,
+					].filter( Boolean ),
+				},
+			];
+		} )
+		.filter( Boolean );
+
+	return [ { [ `h${ headingLevel }` ]: 'Props' }, ...propsJson ];
+}
+
+module.exports = {
+	generateMarkdownPropsJson,
+};

package.json

@@ -216,6 +216,7 @@
 		"jest-junit": "13.0.0",
 		"jest-message-util": "29.6.2",
 		"jest-watch-typeahead": "2.2.2",
+		"json2md": "2.0.1",
 		"lerna": "7.1.4",
 		"lint-staged": "10.0.2",
 		"make-dir": "3.0.0",
@@ -235,6 +236,7 @@
 		"progress": "2.0.3",
 		"puppeteer-core": "23.1.0",
 		"react": "18.3.1",
+		"react-docgen-typescript": "2.2.2",
 		"react-dom": "18.3.1",
 		"react-native": "0.73.3",
 		"react-native-url-polyfill": "1.1.2",
@@ -282,7 +284,8 @@
 		"distclean": "git clean --force -d -X",
 		"docs:api-ref": "node ./bin/api-docs/update-api-docs.js",
 		"docs:blocks": "node ./bin/api-docs/gen-block-lib-list.js",
-		"docs:build": "npm-run-all docs:gen docs:blocks docs:api-ref docs:theme-ref",
+		"docs:build": "npm-run-all docs:components docs:gen docs:blocks docs:api-ref docs:theme-ref",
+		"docs:components": "node ./bin/api-docs/gen-components-docs",
 		"docs:gen": "node ./docs/tool/index.js",
 		"docs:theme-ref": "node ./bin/api-docs/gen-theme-reference.mjs",
 		"env": "wp-env",

packages/components/schemas/docs-manifest.json

@@ -0,0 +1,38 @@
+{
+	"title": "JSON schema for @wordpress/components README manifests",
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"type": "object",
+	"properties": {
+		"displayName": {
+			"type": "string",
+			"description": "The `displayName` of the component, as determined in code."
+		},
+		"filePath": {
+			"type": "string",
+			"description": "The file path where the component is located."
+		},
+		"subcomponents": {
+			"type": "array",
+			"description": "List of subcomponents related to the component.",
+			"items": {
+				"type": "object",
+				"properties": {
+					"displayName": {
+						"type": "string",
+						"description": "The `displayName` of the subcomponent, as determined in code."
+					},
+					"preferredDisplayName": {
+						"type": "string",
+						"description": "The display name to use in the README, if it is different from the `displayName` as determined in code."
+					},
+					"filePath": {
+						"type": "string",
+						"description": "The file path where the subcomponent is located."
+					}
+				},
+				"required": [ "displayName", "filePath" ]
+			}
+		}
+	},
+	"required": [ "displayName", "filePath" ]
+}