Skip to content

Commit

Permalink
Use a central script instead of one per package to generate docs (#14216
Browse files Browse the repository at this point in the history
)
  • Loading branch information
nosolosw authored and youknowriad committed Mar 20, 2019
1 parent 339489f commit 0434cf2
Show file tree
Hide file tree
Showing 8 changed files with 70 additions and 43 deletions.
29 changes: 29 additions & 0 deletions bin/update-readmes.js
Original file line number Diff line number Diff line change
@@ -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 );
8 changes: 5 additions & 3 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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"
]
}
}
2 changes: 1 addition & 1 deletion packages/docgen/bin/cli.js
Original file line number Diff line number Diff line change
Expand Up @@ -41,4 +41,4 @@ const optionator = require( 'optionator' )( {
} );

const options = optionator.parseArgv( process.argv );
docgen( options._[ 0 ], options );
process.exit( docgen( options._[ 0 ], options ) );
26 changes: 14 additions & 12 deletions packages/docgen/src/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -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 );
};

Expand All @@ -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 );
}
};
Expand All @@ -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';
Expand All @@ -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 );
Expand Down Expand Up @@ -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 );
};
2 changes: 1 addition & 1 deletion packages/docgen/src/markdown/formatter.js
Original file line number Diff line number Diff line change
Expand Up @@ -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' );
Expand Down
2 changes: 1 addition & 1 deletion packages/docgen/src/test/formatter-markdown.js
Original file line number Diff line number Diff line change
Expand Up @@ -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'
);
} );
} );
38 changes: 19 additions & 19 deletions packages/e2e-test-utils/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -372,7 +372,7 @@ is displayed).

**Returns**

`Promise` Promise resolving when publish is complete.
`Promise`: Promise resolving when publish is complete.

### publishPostWithPrePublishChecksDisabled

Expand All @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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

Expand Down
6 changes: 0 additions & 6 deletions packages/e2e-test-utils/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
}

0 comments on commit 0434cf2

Please sign in to comment.