From 21963bf8ee8197c958ab1b3cd62bbbd89e186683 Mon Sep 17 00:00:00 2001 From: Andrew Duthie Date: Thu, 19 Dec 2019 13:20:41 +0100 Subject: [PATCH] Port changes after rebase --- bin/api-docs/update-readmes.js | 156 ++++++++++++++++++++++++----- package-lock.json | 173 ++++++++++++++++++++++++++++++--- package.json | 1 + packages/core-data/README.md | 8 +- packages/docgen/README.md | 4 +- tsconfig.json | 3 +- 6 files changed, 300 insertions(+), 45 deletions(-) diff --git a/bin/api-docs/update-readmes.js b/bin/api-docs/update-readmes.js index fd66e6cbf39d0..8aeff8a5c62c2 100755 --- a/bin/api-docs/update-readmes.js +++ b/bin/api-docs/update-readmes.js @@ -1,35 +1,141 @@ /** - * Node dependencies. + * External dependencies */ -const { join } = require( 'path' ); -const spawnSync = require( 'child_process' ).spawnSync; +const { join, relative, resolve, sep } = require( 'path' ); +const glob = require( 'fast-glob' ); +const execa = require( 'execa' ); +const { Transform } = require( 'stream' ); +const { readFile } = require( 'fs' ).promises; /** - * Local dependencies. + * README file tokens, defined as a tuple of token identifier, source path. + * + * @typedef {[string,string]} WPReadmeFileTokens */ -const getPackages = require( './packages' ); -getPackages().forEach( ( entry ) => { - const [ packageName, targetFiles ] = entry; +/** + * README file data, defined as a tuple of README file path, token details. + * + * @typedef {[string,WPReadmeFileTokens]} WPReadmeFileData + */ + +/** + * Path to packages directory. + * + * @type {string} + */ +const PACKAGES_DIR = resolve( __dirname, '../packages' ); + +/** + * Pattern matching start token of a README file. + * + * @type {RegExp} + */ +const TOKEN_PATTERN = //g; - Object.entries( targetFiles ).forEach( ( [ token, path ] ) => { - // Each target operates over the same file, so it needs to be processed synchronously, - // as to make sure the processes don't overwrite each other. - const { status, stderr } = spawnSync( - join( __dirname, '..', '..', 'node_modules', '.bin', 'docgen' ).replace( / /g, '\\ ' ), - [ - join( 'packages', packageName, path ), - `--output packages/${ packageName }/README.md`, - '--to-token', - `--use-token "${ token }"`, - '--ignore "/unstable|experimental/i"', - ], - { shell: true }, - ); +/** + * Given an absolute file path, returns the package name. + * + * @param {string} file Absolute path. + * + * @return {string} Package name. + */ +function getFilePackage( file ) { + return relative( PACKAGES_DIR, file ).split( sep )[ 0 ]; +} + +/** + * Returns an appropriate glob pattern for the packages directory to match + * relevant for a given set of files. + * + * @param {string[]} files Set of files to match. Pass an empty set to match + * all packages. + * + * @return {string} Packages glob pattern. + */ +function getPackagePattern( files ) { + if ( ! files.length ) { + return '*'; + } + + // Since brace expansion doesn't work with a single package, special-case + // the pattern for the singular match. + const packages = files.map( getFilePackage ); + return packages.length === 1 ? + packages[ 0 ] : + '{' + packages.join() + '}'; +} - if ( status !== 0 ) { - process.stderr.write( `${ packageName } ${ stderr.toString() }\n` ); - process.exit( 1 ); +/** + * Stream transform which filters out README files to include only those + * containing matched token pattern, yielding a tuple of the file and its + * matched tokens. + * + * @type {Transform} + */ +const filterTokenTransform = new Transform( { + objectMode: true, + + async transform( file, _encoding, callback ) { + let content; + try { + content = await readFile( file, 'utf8' ); + } catch {} + + if ( content ) { + const tokens = []; + + for ( const match of content.matchAll( TOKEN_PATTERN ) ) { + const [ , token, path = 'src/index.js' ] = match; + tokens.push( [ token, path ] ); + } + + if ( tokens.length ) { + this.push( [ file, tokens ] ); + } } - } ); + + callback(); + }, } ); + +/** + * Optional process arguments for which to generate documentation. + * + * @type {string[]} + */ +const files = process.argv.slice( 2 ); + +glob.stream( `${ PACKAGES_DIR }/${ getPackagePattern( files ) }/README.md` ) + .pipe( filterTokenTransform ) + .on( 'data', async ( /** @type {WPReadmeFileData} */ data ) => { + const [ file, tokens ] = data; + + const packageName = getFilePackage( file ); + + // Each file can have more than one placeholder content to update, + // each represented by tokens. The docgen script updates one token at a time, + // so the tokens must be replaced in sequence to prevent the processes + // from overriding each other. + for ( const [ token, path ] of tokens ) { + try { + await execa( + join( __dirname, '..', 'node_modules', '.bin', 'docgen' ), + [ + join( 'packages', packageName, path ), + `--output packages/${ packageName }/README.md`, + '--to-token', + `--use-token "${ token }"`, + '--ignore "/unstable|experimental/i"', + ], + { shell: true } + ); + } catch ( error ) { + // Disable reason: Errors should log to console. + + // eslint-disable-next-line no-console + console.error( error ); + process.exit( 1 ); + } + } + } ); diff --git a/package-lock.json b/package-lock.json index 095e45821a459..29fc71271463c 100644 --- a/package-lock.json +++ b/package-lock.json @@ -16073,17 +16073,125 @@ "dev": true }, "execa": { - "version": "0.7.0", - "resolved": "https://registry.npmjs.org/execa/-/execa-0.7.0.tgz", - "integrity": "sha1-lEvs00zEHuMqY6n68nrVpl/Fl3c=", - "requires": { - "cross-spawn": "^5.0.1", - "get-stream": "^3.0.0", - "is-stream": "^1.1.0", - "npm-run-path": "^2.0.0", - "p-finally": "^1.0.0", - "signal-exit": "^3.0.0", - "strip-eof": "^1.0.0" + "version": "3.4.0", + "resolved": "https://registry.npmjs.org/execa/-/execa-3.4.0.tgz", + "integrity": "sha512-r9vdGQk4bmCuK1yKQu1KTwcT2zwfWdbdaXfCtAh+5nU/4fSX+JAb7vZGvI5naJrQlvONrEB20jeruESI69530g==", + "dev": true, + "requires": { + "cross-spawn": "^7.0.0", + "get-stream": "^5.0.0", + "human-signals": "^1.1.1", + "is-stream": "^2.0.0", + "merge-stream": "^2.0.0", + "npm-run-path": "^4.0.0", + "onetime": "^5.1.0", + "p-finally": "^2.0.0", + "signal-exit": "^3.0.2", + "strip-final-newline": "^2.0.0" + }, + "dependencies": { + "cross-spawn": { + "version": "7.0.1", + "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.1.tgz", + "integrity": "sha512-u7v4o84SwFpD32Z8IIcPZ6z1/ie24O6RU3RbtL5Y316l3KuHVPx9ItBgWQ6VlfAFnRnTtMUrsQ9MUUTuEZjogg==", + "dev": true, + "requires": { + "path-key": "^3.1.0", + "shebang-command": "^2.0.0", + "which": "^2.0.1" + } + }, + "get-stream": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/get-stream/-/get-stream-5.1.0.tgz", + "integrity": "sha512-EXr1FOzrzTfGeL0gQdeFEvOMm2mzMOglyiOXSTpPC+iAjAKftbr3jpCMWynogwYnM+eSj9sHGc6wjIcDvYiygw==", + "dev": true, + "requires": { + "pump": "^3.0.0" + } + }, + "is-stream": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/is-stream/-/is-stream-2.0.0.tgz", + "integrity": "sha512-XCoy+WlUr7d1+Z8GgSuXmpuUFC9fOhRXglJMx+dwLKTkL44Cjd4W1Z5P+BQZpr+cR93aGP4S/s7Ftw6Nd/kiEw==", + "dev": true + }, + "merge-stream": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/merge-stream/-/merge-stream-2.0.0.tgz", + "integrity": "sha512-abv/qOcuPfk3URPfDzmZU1LKmuw8kT+0nIHvKrKgFrwifol/doWcdA4ZqsWQ8ENrFKkd67Mfpo/LovbIUsbt3w==", + "dev": true + }, + "mimic-fn": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/mimic-fn/-/mimic-fn-2.1.0.tgz", + "integrity": "sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg==", + "dev": true + }, + "npm-run-path": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/npm-run-path/-/npm-run-path-4.0.0.tgz", + "integrity": "sha512-8eyAOAH+bYXFPSnNnKr3J+yoybe8O87Is5rtAQ8qRczJz1ajcsjg8l2oZqP+Ppx15Ii3S1vUTjQN2h4YO2tWWQ==", + "dev": true, + "requires": { + "path-key": "^3.0.0" + } + }, + "onetime": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/onetime/-/onetime-5.1.0.tgz", + "integrity": "sha512-5NcSkPHhwTVFIQN+TUqXoS5+dlElHXdpAWu9I0HP20YOtIi+aZ0Ct82jdlILDxjLEAWwvm+qj1m6aEtsDVmm6Q==", + "dev": true, + "requires": { + "mimic-fn": "^2.1.0" + } + }, + "p-finally": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/p-finally/-/p-finally-2.0.1.tgz", + "integrity": "sha512-vpm09aKwq6H9phqRQzecoDpD8TmVyGw70qmWlyq5onxY7tqyTTFVvxMykxQSQKILBSFlbXpypIw2T1Ml7+DDtw==", + "dev": true + }, + "path-key": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz", + "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==", + "dev": true + }, + "pump": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/pump/-/pump-3.0.0.tgz", + "integrity": "sha512-LwZy+p3SFs1Pytd/jYct4wpv49HiYCqd9Rlc5ZVdk0V+8Yzv6jR5Blk3TRmPL1ft69TxP0IMZGJ+WPFU2BFhww==", + "dev": true, + "requires": { + "end-of-stream": "^1.1.0", + "once": "^1.3.1" + } + }, + "shebang-command": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz", + "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==", + "dev": true, + "requires": { + "shebang-regex": "^3.0.0" + } + }, + "shebang-regex": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz", + "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==", + "dev": true + }, + "which": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz", + "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==", + "dev": true, + "requires": { + "isexe": "^2.0.0" + } + } } }, "execall": { @@ -18739,6 +18847,12 @@ "debug": "^3.1.0" } }, + "human-signals": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/human-signals/-/human-signals-1.1.1.tgz", + "integrity": "sha512-SEQu7vl8KjNL2eoGBLF3+wAjpsNfA9XMlXAYj/3EdaNfAlxKthD1xjEQfGOUhllCGGJVNY34bRr6lPINhNjyZw==", + "dev": true + }, "humanize-ms": { "version": "1.2.1", "resolved": "https://registry.npmjs.org/humanize-ms/-/humanize-ms-1.2.1.tgz", @@ -22840,7 +22954,7 @@ "dependencies": { "clone-deep": { "version": "0.2.4", - "resolved": "http://registry.npmjs.org/clone-deep/-/clone-deep-0.2.4.tgz", + "resolved": "https://registry.npmjs.org/clone-deep/-/clone-deep-0.2.4.tgz", "integrity": "sha1-TnPdCen7lxzDhnDF3O2cGJZIHMY=", "dev": true, "requires": { @@ -22874,7 +22988,7 @@ "dependencies": { "kind-of": { "version": "2.0.1", - "resolved": "http://registry.npmjs.org/kind-of/-/kind-of-2.0.1.tgz", + "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-2.0.1.tgz", "integrity": "sha1-AY7HpM5+OobLkUG+UZ0kyPqpgbU=", "dev": true, "requires": { @@ -25550,6 +25664,22 @@ "execa": "^0.7.0", "lcid": "^1.0.0", "mem": "^1.1.0" + }, + "dependencies": { + "execa": { + "version": "0.7.0", + "resolved": "https://registry.npmjs.org/execa/-/execa-0.7.0.tgz", + "integrity": "sha1-lEvs00zEHuMqY6n68nrVpl/Fl3c=", + "requires": { + "cross-spawn": "^5.0.1", + "get-stream": "^3.0.0", + "is-stream": "^1.1.0", + "npm-run-path": "^2.0.0", + "p-finally": "^1.0.0", + "signal-exit": "^3.0.0", + "strip-eof": "^1.0.0" + } + } } }, "os-name": { @@ -32112,6 +32242,23 @@ "dev": true, "requires": { "execa": "^0.7.0" + }, + "dependencies": { + "execa": { + "version": "0.7.0", + "resolved": "https://registry.npmjs.org/execa/-/execa-0.7.0.tgz", + "integrity": "sha1-lEvs00zEHuMqY6n68nrVpl/Fl3c=", + "dev": true, + "requires": { + "cross-spawn": "^5.0.1", + "get-stream": "^3.0.0", + "is-stream": "^1.1.0", + "npm-run-path": "^2.0.0", + "p-finally": "^1.0.0", + "signal-exit": "^3.0.0", + "strip-eof": "^1.0.0" + } + } } }, "terminal-link": { diff --git a/package.json b/package.json index cd6d482c63eee..c55e08233f509 100644 --- a/package.json +++ b/package.json @@ -119,6 +119,7 @@ "enzyme": "3.9.0", "eslint-plugin-eslint-comments": "3.1.2", "eslint-plugin-import": "2.18.2", + "execa": "3.4.0", "fast-glob": "2.2.7", "fbjs": "0.8.17", "glob": "7.1.2", diff --git a/packages/core-data/README.md b/packages/core-data/README.md index 5b5cda9580b62..196e807129a2a 100644 --- a/packages/core-data/README.md +++ b/packages/core-data/README.md @@ -40,7 +40,7 @@ const MyAuthorsList = withSelect( ( select ) => ( { The following set of dispatching action creators are available on the object returned by `wp.data.dispatch( 'core' )`: - + # **addEntities** @@ -211,13 +211,13 @@ _Parameters_ Action triggered to undo the last edit to an entity record, if any. - + ## Selectors The following selectors are available on the object returned by `wp.data.select( 'core' )`: - + # **canUser** @@ -670,6 +670,6 @@ _Returns_ - `boolean`: Whether the entity record is saving or not. - +

Code is Poetry.

diff --git a/packages/docgen/README.md b/packages/docgen/README.md index c62b96fc4e44b..a1fb2b753d667 100644 --- a/packages/docgen/README.md +++ b/packages/docgen/README.md @@ -33,9 +33,9 @@ This command will generate a file named `entry-point-api.md` containing all the * **--output** `(String)`: Output file that will contain the API documentation. * **--to-section** `(String)`: Append generated documentation to this section in the Markdown output. To be used by the default Markdown formatter. Depends on `--output` and bypasses the custom `--formatter` passed, if any. * **--to-token**: Embed generated documentation within the start and end tokens in the Markdown output. To be used by the default Markdown formatter.Depends on `--output` and bypasses the custom `--formatter` passed, if any. - * Start token: `` + * Start token: <!-- START TOKEN(Autogenerated API docs) --> * End token: `` -* **--use-token** `(String)`: This options allows you to customize the string between the tokens. For example, `--use-token my-api` will look up for the start token `` and the end token ``. Depends on `--to-token`. +* **--use-token** `(String)`: This options allows you to customize the string between the tokens. For example, `--use-token my-api` will look up for the start token <!-- START TOKEN(my-api) --> and the end token ``. Depends on `--to-token`. * **--debug**: Run in debug mode, which outputs some intermediate files useful for debugging. ## Examples diff --git a/tsconfig.json b/tsconfig.json index a1854349a9d95..7a57e9c4ee84e 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -4,7 +4,7 @@ "allowSyntheticDefaultImports": true, "checkJs": true, "jsx": "preserve", - "lib": ["dom", "esnext"], + "lib": ["dom", "esnext", "es2020.string"], "module": "commonjs", "noEmit": true, "resolveJsonModule": true, @@ -31,6 +31,7 @@ "noFallthroughCasesInSwitch": true, /* Report errors for fallthrough cases in switch statement. */ }, "include": [ + "./bin/update-readmes.js", "./packages/a11y/**/*.js", "./packages/blob/**/*.js", "./packages/dom-ready/**/*.js",