New package to auto-generate public API documentation (#13329)

docs/manifest.json

@@ -635,6 +635,12 @@
 		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/deprecated/README.md",
 		"parent": "packages"
 	},
+	{
+		"title": "@wordpress/docgen",
+		"slug": "packages-docgen",
+		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/docgen/README.md",
+		"parent": "packages"
+	},
 	{
 		"title": "@wordpress/dom-ready",
 		"slug": "packages-dom-ready",

package.json

@@ -66,6 +66,7 @@
 		"@wordpress/babel-preset-default": "file:packages/babel-preset-default",
 		"@wordpress/browserslist-config": "file:packages/browserslist-config",
 		"@wordpress/custom-templated-path-webpack-plugin": "file:packages/custom-templated-path-webpack-plugin",
+		"@wordpress/docgen": "file:packages/docgen",
 		"@wordpress/e2e-test-utils": "file:packages/e2e-test-utils",
 		"@wordpress/e2e-tests": "file:packages/e2e-tests",
 		"@wordpress/eslint-plugin": "file:packages/eslint-plugin",
@@ -161,6 +162,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",
 		"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",

packages/docgen/.npmrc

@@ -0,0 +1 @@
+package-lock=false

packages/docgen/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 1.0.0 (Unreleased)
+
+- Initial release

packages/docgen/README.md

@@ -0,0 +1,250 @@
+# `docgen`
+
+`docgen` helps you to generate the _public API_ of your code. Given an entry point file, it outputs the ES6 export statements and their corresponding JSDoc comments in human-readable format.
+
+Some characteristics:
+
+* If the export statement doesn't contain any JSDoc, it'll look up for JSDoc up to the declaration.
+* It can resolve relative dependencies, either files or directories. For example, `import default from './dependency'` will find `dependency.js` or `dependency/index.js`
+
+## Installation
+
+Install the module
+
+```bash
+npm install @wordpress/docgen --save-dev
+```
+
+## Usage
+
+```bash
+npx docgen <entry-point.js>
+```
+
+This command will generate a file named `entry-point-api.md` containing all the exports and their JSDoc comments.
+
+### CLI options
+
+* **--formatter** `(String)`: A path to a custom formatter to control the contents of the output file. It should be a CommonJS module that exports a function that takes as input:
+  * *rootDir* `(String)`: current working directory as seen by docgen.
+  * *docPath* `(String)`: path of the output document to generate.
+  * *symbols* `(Array)`: the symbols found.
+* **--ignore** `(RegExp)`: A regular expression used to ignore symbols whose name match it.
+* **--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(Autogenerated API docs) -->`
+  * End token: `<!-- END TOKEN(Autogenerated API docs) -->`
+* **--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 `<!-- END TOKEN(my-api) -->`. Depends on `--to-token`.
+* **--debug**: Run in debug mode, which outputs some intermediate files useful for debugging.
+
+## Examples
+
+### Default export
+
+Entry point `index.js`:
+
+```js
+/**
+ * Adds two numbers.
+ *
+ * @param {number} term1 First number.
+ * @param {number} term2 Second number.
+ * @return {number} The result of adding the two numbers.
+ */
+export default function addition( term1, term2 ) {
+	// Implementation would go here.
+}
+```
+
+Output of `npx docgen index.js` would be `index-api.js`:
+
+```markdown
+# API
+
+## default
+
+[example.js#L8-L10](example.js#L8-L10)
+
+Adds two numbers.
+
+**Parameters**
+
+- **term1** `number`: First number.
+- **term2** `number`: Second number.
+
+**Returns**
+
+`number` The result of adding the two numbers.
+```
+
+### Named export
+
+Entry point `index.js`:
+
+```js
+/**
+ * Adds two numbers.
+ *
+ * @param {number} term1 First number.
+ * @param {number} term2 Second number.
+ * @return {number} The result of adding the two numbers.
+ */
+function addition( term1, term2 ) {
+	return term1 + term2;
+}
+
+/**
+ * Adds two numbers.
+ *
+ * @deprecated Use `addition` instead.
+ *
+ * @param {number} term1 First number.
+ * @param {number} term2 Second number.
+ * @return {number} The result of adding the two numbers.
+ */
+function count( term1, term2 ) {
+	return term1 + term2;
+}
+
+export { count, addition };
+```
+
+Output of `npx docgen index.js` would be `index-api.js`:
+
+```markdown
+# API
+
+## addition
+
+[example.js#L25-L25](example.js#L25-L25)
+
+Adds two numbers.
+
+**Parameters**
+
+- **term1** `number`: First number.
+- **term2** `number`: Second number.
+
+**Returns**
+
+`number` The result of adding the two numbers.
+
+## count
+
+[example.js#L25-L25](example.js#L25-L25)
+
+> **Deprecated** Use `addition` instead.
+
+Adds two numbers.
+
+**Parameters**
+
+- **term1** `number`: First number.
+- **term2** `number`: Second number.
+
+**Returns**
+
+`number` The result of adding the two numbers.
+```
+
+### Namespace export
+
+Let the entry point be `index.js`:
+
+```js
+export * from './count';
+```
+
+with `./count/index.js` contents being:
+
+```js
+/**
+ * Substracts two numbers.
+ *
+ * @example
+ *
+ * ```js
+ * const result = substraction( 5, 2 );
+ * console.log( result ); // Will log 3
+ * ```
+ *
+ * @param {number} term1 First number.
+ * @param {number} term2 Second number.
+ * @return {number} The result of subtracting the two numbers.
+ */
+export function substraction( term1, term2 ) {
+	return term1 - term2;
+}
+
+/**
+ * Adds two numbers.
+ *
+  * @example
+ *
+ * ```js
+ * const result = addition( 5, 2 );
+ * console.log( result ); // Will log 7
+ * ```
+ *
+ * @param {number} term1 First number.
+ * @param {number} term2 Second number.
+ * @return {number} The result of adding the two numbers.
+ */
+export function addition( term1, term2 ) {
+	// Implementation would go here.
+	return term1 - term2;
+}
+```
+
+Output of `npx docgen index.js` would be `index-api.js`:
+
+````markdown
+# API
+
+## addition
+
+[example-module.js#L1-L1](example-module.js#L1-L1)
+
+Adds two numbers.
+
+**Usage**
+
+```js
+const result = addition( 5, 2 );
+console.log( result ); // Will log 7
+```
+
+**Parameters**
+
+- **term1** `number`: First number.
+- **term2** `number`: Second number.
+
+**Returns**
+
+`number` The result of adding the two numbers.
+
+## substraction
+
+[example-module.js#L1-L1](example-module.js#L1-L1)
+
+Substracts two numbers.
+
+**Usage**
+
+```js
+const result = substraction( 5, 2 );
+console.log( result ); // Will log 3
+```
+
+**Parameters**
+
+- **term1** `number`: First number.
+- **term2** `number`: Second number.
+
+**Returns**
+
+`number` The result of subtracting the two numbers.
+````
+
+<br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>

packages/docgen/bin/cli.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+const docgen = require( '../src' );
+
+const optionator = require( 'optionator' )( {
+	prepend: 'Usage: node <path-to-docgen> <relative-path-to-entry-point>',
+	options: [ {
+		option: 'formatter',
+		type: 'String',
+		description: 'A custom function to format the generated documentation. By default, a Markdown formatter will be used.',
+	}, {
+		option: 'output',
+		type: 'String',
+		description: 'Output file to contain the API documentation.',
+	}, {
+		option: 'ignore',
+		type: 'RegExp',
+		description: 'A regular expression used to ignore symbols whose name match it.',
+	}, {
+		option: 'to-section',
+		type: 'String',
+		description: 'Append generated documentation to this section in the Markdown output. To be used by the default Markdown formatter.',
+		dependsOn: 'output',
+	}, {
+		option: 'to-token',
+		type: 'Boolean',
+		description: 'Embed generated documentation within this token in the Markdown output. To be used by the default Markdown formatter.',
+		dependsOn: 'output',
+	}, {
+		option: 'use-token',
+		type: 'String',
+		default: 'Autogenerated API docs',
+		description: 'Add this string to the start/end tokens.',
+		dependsOn: 'to-token',
+	}, {
+		option: 'debug',
+		type: 'Boolean',
+		default: false,
+		description: 'Run in debug mode, which outputs some intermediate files useful for debugging.',
+	} ],
+} );
+
+const options = optionator.parseArgv( process.argv );
+docgen( options._[ 0 ], options );