diff --git a/bin/update-readmes.js b/bin/update-readmes.js new file mode 100755 index 00000000000000..c094bc57a5b2bc --- /dev/null +++ b/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 ); diff --git a/package.json b/package.json index fdd2122723c81f..0f3b37a094e24f 100644 --- a/package.json +++ b/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" ] } } diff --git a/packages/docgen/bin/cli.js b/packages/docgen/bin/cli.js index bcc1a6f1e245d0..e5e67d5d89f3cb 100755 --- a/packages/docgen/bin/cli.js +++ b/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 ) ); diff --git a/packages/docgen/src/index.js b/packages/docgen/src/index.js index 1bc2e71a37897a..0fef8a2563a597 100644 --- a/packages/docgen/src/index.js +++ b/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 ); }; diff --git a/packages/docgen/src/markdown/formatter.js b/packages/docgen/src/markdown/formatter.js index d9e41536f2f9a0..84b09a1b441f5c 100644 --- a/packages/docgen/src/markdown/formatter.js +++ b/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' ); diff --git a/packages/docgen/src/test/formatter-markdown.js b/packages/docgen/src/test/formatter-markdown.js index cd7e66a12e2678..953768eb5c604b 100644 --- a/packages/docgen/src/test/formatter-markdown.js +++ b/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' ); } ); } ); diff --git a/packages/e2e-test-utils/README.md b/packages/e2e-test-utils/README.md index 4958201be72972..845b6725cf82f3 100644 --- a/packages/e2e-test-utils/README.md +++ b/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 diff --git a/packages/e2e-test-utils/package.json b/packages/e2e-test-utils/package.json index 0a6871bff1d76c..f31d67677475e2 100644 --- a/packages/e2e-test-utils/package.json +++ b/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" } }