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"
  }
 }