Use a central script instead of one per package to generate docs (#14216

)

bin/update-readmes.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+const path = require( 'path' );
+const childProcess = require( 'child_process' );
+
+const packages = [
+	'e2e-test-utils',
+];
+
+let aggregatedExitCode = 0;
+packages.forEach( ( packageName ) => {
+	const args = [
+		`packages/${ packageName }/src/index.js`,
+		`--output packages/${ packageName }/README.md`,
+		'--to-token',
+	];
+	const pathToDocGen = path.join( __dirname, '..', 'node_modules', '.bin', 'docgen' );
+	const { status, stderr } = childProcess.spawnSync(
+		pathToDocGen,
+		args,
+		{ shell: true },
+	);
+	if ( status !== 0 ) {
+		aggregatedExitCode = status;
+		process.stderr.write( `${ stderr }\n` );
+	}
+} );
+
+process.exit( aggregatedExitCode );

package.json

@@ -162,8 +162,7 @@
 		"predev": "npm run check-engines",
 		"dev": "npm run build:packages && concurrently \"wp-scripts start\" \"npm run dev:packages\"",
 		"dev:packages": "node ./bin/packages/watch.js",
-		"docs:build": "node docs/tool",
-		"docs:generate": "lerna run docs:generate",
+		"docs:build": "node ./docs/tool && node ./bin/update-readmes",
 		"fixtures:clean": "rimraf \"packages/e2e-tests/fixtures/blocks/*.+(json|serialized.html)\"",
 		"fixtures:server-registered": "docker-compose run -w /var/www/html/wp-content/plugins/gutenberg --rm wordpress ./bin/get-server-blocks.php > test/integration/full-content/server-registered.json",
 		"fixtures:generate": "npm run fixtures:server-registered && cross-env GENERATE_MISSING_FIXTURES=y npm run test-unit",
@@ -204,7 +203,10 @@
 			"wp-scripts lint-js"
 		],
 		"{docs/{toc.json,tool/*.js},packages/{*/README.md,*/src/{actions,selectors}.js,components/src/*/**/README.md}}": [
-			"npm run docs:build"
+			"node ./docs/tool"
+		],
+		"packages/**/*.js": [
+			"node ./bin/update-readmes"
 		]
 	}
 }

packages/docgen/bin/cli.js

@@ -41,4 +41,4 @@ const optionator = require( 'optionator' )( {
 } );
 
 const options = optionator.parseArgv( process.argv );
-docgen( options._[ 0 ], options );
+process.exit( docgen( options._[ 0 ], options ) );

packages/docgen/src/index.js

@@ -28,11 +28,11 @@ const relativeToAbsolute = ( basePath, relativePath ) => {
 	if ( fs.existsSync( targetFile ) ) {
 		return targetFile;
 	}
-	process.stdout.write( '\nRelative path does not exists.' );
-	process.stdout.write( '\n' );
-	process.stdout.write( `\nBase: ${ basePath }` );
-	process.stdout.write( `\nRelative: ${ relativePath }` );
-	process.stdout.write( '\n\n' );
+	process.stderr.write( '\nRelative path does not exists.' );
+	process.stderr.write( '\n' );
+	process.stderr.write( `\nBase: ${ basePath }` );
+	process.stderr.write( `\nRelative: ${ relativePath }` );
+	process.stderr.write( '\n\n' );
 	process.exit( 1 );
 };
 
@@ -54,8 +54,8 @@ const processFile = ( rootDir, inputFile ) => {
 		currentFileStack.pop( inputFile );
 		return result;
 	} catch ( e ) {
-		process.stdout.write( `\n${ e }` );
-		process.stdout.write( '\n\n' );
+		process.stderr.write( `\n${ e }` );
+		process.stderr.write( '\n\n' );
 		process.exit( 1 );
 	}
 };
@@ -66,8 +66,8 @@ const runCustomFormatter = ( customFormatterFile, rootDir, doc, symbols, heading
 		const output = customFormatter( rootDir, doc, symbols, headingTitle );
 		fs.writeFileSync( doc, output );
 	} catch ( e ) {
-		process.stdout.write( `\n${ e }` );
-		process.stdout.write( '\n\n' );
+		process.stderr.write( `\n${ e }` );
+		process.stderr.write( '\n\n' );
 		process.exit( 1 );
 	}
 	return 'custom formatter';
@@ -80,9 +80,9 @@ module.exports = function( sourceFile, options ) {
 	// Input: process CLI args, prepare files, etc
 	const processDir = process.cwd();
 	if ( sourceFile === undefined ) {
-		process.stdout.write( '\n' );
-		process.stdout.write( 'No source file provided' );
-		process.stdout.write( '\n\n' );
+		process.stderr.write( '\n' );
+		process.stderr.write( 'No source file provided' );
+		process.stderr.write( '\n\n' );
 		process.exit( 1 );
 	}
 	sourceFile = path.join( processDir, sourceFile );
@@ -123,4 +123,6 @@ module.exports = function( sourceFile, options ) {
 		fs.writeFileSync( tokens, JSON.stringify( result.tokens ) );
 		fs.writeFileSync( ast, JSON.stringify( result.ast ) );
 	}
+
+	process.exit( 0 );
 };

packages/docgen/src/markdown/formatter.js

@@ -113,7 +113,7 @@ module.exports = function( rootDir, docPath, symbols, headingTitle, headingStart
 			formatTag(
 				'Returns',
 				getTagsByName( symbol.tags, 'return' ),
-				( tag ) => `\n\`${ tag.type }\` ${ cleanSpaces( tag.description ) }`,
+				( tag ) => `\n\`${ tag.type }\`: ${ cleanSpaces( tag.description ) }`,
 				docs
 			);
 			docs.push( '\n' );

packages/docgen/src/test/formatter-markdown.js

@@ -28,7 +28,7 @@ describe( 'Formatter', () => {
 			lineEnd: 2,
 		} ], 'API docs' );
 		expect( docs ).toBe(
-			'# API docs\n\n## myDeclaration\n\n[home/my-path/docs-code.js#L1-L2](home/my-path/docs-code.js#L1-L2)\n\nMy declaration example.\n\n**Parameters**\n\n- **firstParam** `number`: First declaration parameter.\n\n**Returns**\n\n`number` The result of the declaration.\n'
+			'# API docs\n\n## myDeclaration\n\n[home/my-path/docs-code.js#L1-L2](home/my-path/docs-code.js#L1-L2)\n\nMy declaration example.\n\n**Parameters**\n\n- **firstParam** `number`: First declaration parameter.\n\n**Returns**\n\n`number`: The result of the declaration.\n'
 		);
 	} );
 } );

packages/e2e-test-utils/README.md

@@ -32,7 +32,7 @@ Verifies if publish checks are enabled.
 
 **Returns**
 
-`boolean` Boolean which represents the state of prepublish checks.
+`boolean`: Boolean which represents the state of prepublish checks.
 
 ### clearLocalStorage
 
@@ -88,7 +88,7 @@ Creates a function to determine if a request is embedding a certain URL.
 
 **Returns**
 
-`function` Function that determines if a request is for the embed API, embedding a specific URL.
+`function`: Function that determines if a request is for the embed API, embedding a specific URL.
 
 ### createJSONResponse
 
@@ -102,7 +102,7 @@ Respond to a request with a JSON response.
 
 **Returns**
 
-`Promise` Promise that responds to a request with the mock JSON response.
+`Promise`: Promise that responds to a request with the mock JSON response.
 
 ### createNewPost
 
@@ -127,7 +127,7 @@ Creates new URL by parsing base URL, WPPath and query string.
 
 **Returns**
 
-`string` String which represents full URL.
+`string`: String which represents full URL.
 
 ### createURLMatcher
 
@@ -141,7 +141,7 @@ Creates a function to determine if a request is calling a URL with the substring
 
 **Returns**
 
-`function` Function that determines if a request's URL contains substring.
+`function`: Function that determines if a request's URL contains substring.
 
 ### deactivatePlugin
 
@@ -180,7 +180,7 @@ Verifies that the edit post sidebar is opened, and if it is not, opens it.
 
 **Returns**
 
-`Promise` Promise resolving once the edit post sidebar is opened.
+`Promise`: Promise resolving once the edit post sidebar is opened.
 
 ### findSidebarPanelToggleButtonWithTitle
 
@@ -194,7 +194,7 @@ Finds a sidebar panel with the provided title.
 
 **Returns**
 
-`?ElementHandle` Object that represents an in-page DOM element.
+`?ElementHandle`: Object that represents an in-page DOM element.
 
 ### findSidebarPanelWithTitle
 
@@ -208,7 +208,7 @@ Finds the button responsible for toggling the sidebar panel with the provided ti
 
 **Returns**
 
-`?ElementHandle` Object that represents an in-page DOM element.
+`?ElementHandle`: Object that represents an in-page DOM element.
 
 ### getAllBlocks
 
@@ -218,7 +218,7 @@ Returns an array with all blocks; Equivalent to calling wp.data.select( 'core/ed
 
 **Returns**
 
-`Promise` Promise resolving with an array containing all blocks in the document.
+`Promise`: Promise resolving with an array containing all blocks in the document.
 
 ### getAvailableBlockTransforms
 
@@ -229,7 +229,7 @@ that the current selected block can be transformed into.
 
 **Returns**
 
-`Promise` Promise resolving with an array containing all possible block transforms
+`Promise`: Promise resolving with an array containing all possible block transforms
 
 ### getEditedPostContent
 
@@ -239,7 +239,7 @@ Returns a promise which resolves with the edited post content (HTML string).
 
 **Returns**
 
-`Promise` Promise resolving with post content markup.
+`Promise`: Promise resolving with post content markup.
 
 ### hasBlockSwitcher
 
@@ -249,7 +249,7 @@ Returns a boolean indicating if the current selected block has a block switcher
 
 **Returns**
 
-`Promise` Promise resolving with a boolean.
+`Promise`: Promise resolving with a boolean.
 
 ### insertBlock
 
@@ -287,7 +287,7 @@ Checks if current URL is a WordPress path.
 
 **Returns**
 
-`boolean` Boolean represents whether current URL is or not a WordPress path.
+`boolean`: Boolean represents whether current URL is or not a WordPress path.
 
 ### loginUser
 
@@ -315,7 +315,7 @@ deserialised JSON response for the request.
 
 **Returns**
 
-`Promise` Promise that uses `mockCheck` to see if a request should be mocked with `mock`, and optionally transforms the response with `responseObjectTransform`.
+`Promise`: Promise that uses `mockCheck` to see if a request should be mocked with `mock`, and optionally transforms the response with `responseObjectTransform`.
 
 ### observeFocusLoss
 
@@ -349,7 +349,7 @@ Presses the given keyboard key a number of times in sequence.
 
 **Returns**
 
-`Promise` Promise resolving when key presses complete.
+`Promise`: Promise resolving when key presses complete.
 
 ### pressKeyWithModifier
 
@@ -372,7 +372,7 @@ is displayed).
 
 **Returns**
 
-`Promise` Promise resolving when publish is complete.
+`Promise`: Promise resolving when publish is complete.
 
 ### publishPostWithPrePublishChecksDisabled
 
@@ -383,7 +383,7 @@ resolving once the request is complete (once a notice is displayed).
 
 **Returns**
 
-`Promise` Promise resolving when publish is complete.
+`Promise`: Promise resolving when publish is complete.
 
 ### saveDraft
 
@@ -394,7 +394,7 @@ Saves the post as a draft, resolving once the request is complete (once the
 
 **Returns**
 
-`Promise` Promise resolving when draft save is complete.
+`Promise`: Promise resolving when draft save is complete.
 
 ### searchForBlock
 
@@ -438,7 +438,7 @@ Sets code editor content
 
 **Returns**
 
-`Promise` Promise resolving with an array containing all blocks in the document.
+`Promise`: Promise resolving with an array containing all blocks in the document.
 
 ### setUpResponseMocking
 

packages/e2e-test-utils/package.json

@@ -33,17 +33,11 @@
 		"lodash": "^4.17.11",
 		"node-fetch": "^1.7.3"
 	},
-	"devDependencies": {
-		"@wordpress/docgen": "file:../docgen"
-	},
 	"peerDependencies": {
 		"jest": ">=24",
 		"puppeteer": ">=1.6"
 	},
 	"publishConfig": {
 		"access": "public"
-	},
-	"scripts": {
-		"docs:generate": "docgen ./src/index.js --output ./README.md --to-token"
 	}
 }