From 1884dcbf77d29981856c3746804399ac8ba5cdac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Mon, 4 Mar 2019 14:29:48 +0100 Subject: [PATCH 1/7] Use a central script instead of one per package --- bin/generate-docs.sh | 3 +++ package.json | 2 +- packages/e2e-test-utils/package.json | 6 ------ 3 files changed, 4 insertions(+), 7 deletions(-) create mode 100755 bin/generate-docs.sh diff --git a/bin/generate-docs.sh b/bin/generate-docs.sh new file mode 100755 index 0000000000000..c7ec1314d9b51 --- /dev/null +++ b/bin/generate-docs.sh @@ -0,0 +1,3 @@ +#!/bin/bash + +npx docgen packages/e2e-test-utils/src/index.js --output packages/e2e-test-utils/README.md --to-token diff --git a/package.json b/package.json index fdd2122723c81..5b59d0298cc95 100644 --- a/package.json +++ b/package.json @@ -163,7 +163,7 @@ "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:generate": "./bin/generate-docs.sh", "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", diff --git a/packages/e2e-test-utils/package.json b/packages/e2e-test-utils/package.json index 0a6871bff1d76..f31d67677475e 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" } } From 9ae7104ed8d1200190ed93d420893a878d16603e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Mon, 4 Mar 2019 14:53:11 +0100 Subject: [PATCH 2/7] Prepare to add more packages --- bin/generate-docs.sh | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/bin/generate-docs.sh b/bin/generate-docs.sh index c7ec1314d9b51..afdebea2977d4 100755 --- a/bin/generate-docs.sh +++ b/bin/generate-docs.sh @@ -1,3 +1,10 @@ #!/bin/bash -npx docgen packages/e2e-test-utils/src/index.js --output packages/e2e-test-utils/README.md --to-token +declare -a packages=( + "e2e-test-utils" +) + +for package in "${packages[@]}" +do + npx docgen packages/${package}/src/index.js --output packages/${package}/README.md --to-token; +done From b15166ca9efb61ec5421ad462d8836528c5bb023 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Mon, 4 Mar 2019 18:46:04 +0100 Subject: [PATCH 3/7] Proper exit code and stderr status for docgen package --- packages/docgen/bin/cli.js | 2 +- packages/docgen/src/index.js | 26 ++++++++++++++------------ 2 files changed, 15 insertions(+), 13 deletions(-) diff --git a/packages/docgen/bin/cli.js b/packages/docgen/bin/cli.js index bcc1a6f1e245d..e5e67d5d89f3c 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 1bc2e71a37897..0fef8a2563a59 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 ); }; From e172a5906bafad7496b38a370e5bbf0f4ae97acb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Mon, 4 Mar 2019 19:06:08 +0100 Subject: [PATCH 4/7] Merge docs:build and docs:generate --- bin/generate-docs.sh | 10 ---------- bin/update-readmes.js | 29 +++++++++++++++++++++++++++++ package.json | 3 +-- 3 files changed, 30 insertions(+), 12 deletions(-) delete mode 100755 bin/generate-docs.sh create mode 100755 bin/update-readmes.js diff --git a/bin/generate-docs.sh b/bin/generate-docs.sh deleted file mode 100755 index afdebea2977d4..0000000000000 --- a/bin/generate-docs.sh +++ /dev/null @@ -1,10 +0,0 @@ -#!/bin/bash - -declare -a packages=( - "e2e-test-utils" -) - -for package in "${packages[@]}" -do - npx docgen packages/${package}/src/index.js --output packages/${package}/README.md --to-token; -done diff --git a/bin/update-readmes.js b/bin/update-readmes.js new file mode 100755 index 0000000000000..c094bc57a5b2b --- /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 5b59d0298cc95..e6d7b1e5f2506 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": "./bin/generate-docs.sh", + "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", From 4689fea1717126ec0ff13f4314d363b7d4d99b5c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Mon, 4 Mar 2019 19:24:13 +0100 Subject: [PATCH 5/7] Update readmes on pre-commit --- package.json | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/package.json b/package.json index e6d7b1e5f2506..0f3b37a094e24 100644 --- a/package.json +++ b/package.json @@ -203,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" ] } } From 116d80bc3d9197014e560e8cca3733fb913a9293 Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Tue, 5 Mar 2019 09:03:43 +0100 Subject: [PATCH 6/7] Update output format for the return value --- packages/docgen/src/markdown/formatter.js | 2 +- packages/e2e-test-utils/README.md | 38 +++++++++++------------ 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/packages/docgen/src/markdown/formatter.js b/packages/docgen/src/markdown/formatter.js index d9e41536f2f9a..84b09a1b441f5 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/e2e-test-utils/README.md b/packages/e2e-test-utils/README.md index 4958201be7297..845b6725cf82f 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 From a4e3d4c9dc9f4cbc667bc2c161f991e4167fc76a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Tue, 5 Mar 2019 11:49:46 +0100 Subject: [PATCH 7/7] Adapt formatter tests to API changes --- packages/docgen/src/test/formatter-markdown.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docgen/src/test/formatter-markdown.js b/packages/docgen/src/test/formatter-markdown.js index cd7e66a12e267..953768eb5c604 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' ); } ); } );