From 8353683e256f1ad5e73942e1ae79ccf7c138cb56 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 +++ 1 file changed, 3 insertions(+) create mode 100755 bin/generate-docs.sh diff --git a/bin/generate-docs.sh b/bin/generate-docs.sh new file mode 100755 index 00000000000000..c7ec1314d9b519 --- /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 From 4975b218bc5621241a975797cc2f726486fd5202 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 c7ec1314d9b519..afdebea2977d40 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 768bda0321a67844ad60d03f8e8d409733fb5639 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 3/7] Merge docs:build and docs:generate --- bin/generate-docs.sh | 10 ---------- 1 file changed, 10 deletions(-) delete mode 100755 bin/generate-docs.sh diff --git a/bin/generate-docs.sh b/bin/generate-docs.sh deleted file mode 100755 index afdebea2977d40..00000000000000 --- 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 From 98a0a468afabfd4c316537a3577036a0914a7076 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Fri, 1 Mar 2019 20:36:20 +0100 Subject: [PATCH 4/7] Autogenerated docs and setup for shortcode --- packages/shortcode/README.md | 147 ++++++++++++++++++++++++++++++++ packages/shortcode/package.json | 6 ++ 2 files changed, 153 insertions(+) diff --git a/packages/shortcode/README.md b/packages/shortcode/README.md index 4887cf2fdcbf7b..dc7df6b0b45089 100644 --- a/packages/shortcode/README.md +++ b/packages/shortcode/README.md @@ -12,4 +12,151 @@ npm install @wordpress/shortcode --save _This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for ES2015+ such as lower versions of IE then using [core-js](https://github.com/zloirock/core-js) or [@babel/polyfill](https://babeljs.io/docs/en/next/babel-polyfill) will add support for these methods. Learn more about it in [Babel docs](https://babeljs.io/docs/en/next/caveats)._ +## API + + + +### attrs + +[src/index.js#L167-L210](src/index.js#L167-L210) + +Parse shortcode attributes. + +Shortcodes accept many types of attributes. These can chiefly be divided into +named and numeric attributes: + +Named attributes are assigned on a key/value basis, while numeric attributes +are treated as an array. + +Named attributes can be formatted as either `name="value"`, `name='value'`, +or `name=value`. Numeric attributes can be formatted as `"value"` or just +`value`. + +**Parameters** + +- **text** `string`: Serialised shortcode attributes. + +**Returns** + +`WPShortcodeAttrs` Parsed shortcode attributes. + +### default + +[src/index.js#L363-L363](src/index.js#L363-L363) + +Creates a shortcode instance. + +To access a raw representation of a shortcode, pass an `options` object, +containing a `tag` string, a string or object of `attrs`, a string indicating +the `type` of the shortcode ('single', 'self-closing', or 'closed'), and a +`content` string. + +**Parameters** + +- **options** `Object`: Options as described. + +**Returns** + +`WPShortcode` Shortcode instance. + +### fromMatch + +[src/index.js#L223-L240](src/index.js#L223-L240) + +Generate a Shortcode Object from a RegExp match. + +Accepts a `match` object from calling `regexp.exec()` on a `RegExp` generated +by `regexp()`. `match` can also be set to the `arguments` from a callback +passed to `regexp.replace()`. + +**Parameters** + +- **match** `Array`: Match array. + +**Returns** + +`WPShortcode` Shortcode instance. + +### next + +[src/index.js#L45-L80](src/index.js#L45-L80) + +Find the next matching shortcode. + +**Parameters** + +- **tag** `string`: Shortcode tag. +- **text** `string`: Text to search. +- **index** `number`: Index to start search from. + +**Returns** + +`?WPShortcodeMatch` Matched information. + +### regexp + +[src/index.js#L146-L148](src/index.js#L146-L148) + +Generate a RegExp to identify a shortcode. + +The base regex is functionally equivalent to the one found in +`get_shortcode_regex()` in `wp-includes/shortcodes.php`. + +Capture groups: + +1. An extra `[` to allow for escaping shortcodes with double `[[]]` +2. The shortcode name +3. The shortcode argument list +4. The self closing `/` +5. The content of a shortcode when it wraps some content. +6. The closing tag. +7. An extra `]` to allow for escaping shortcodes with double `[[]]` + +**Parameters** + +- **tag** `string`: Shortcode tag. + +**Returns** + +`RegExp` Shortcode RegExp. + +### replace + +[src/index.js#L92-L107](src/index.js#L92-L107) + +Replace matching shortcodes in a block of text. + +**Parameters** + +- **tag** `string`: Shortcode tag. +- **text** `string`: Text to search. +- **callback** `Function`: Function to process the match and return replacement string. + +**Returns** + +`string` Text with shortcodes replaced. + +### string + +[src/index.js#L122-L124](src/index.js#L122-L124) + +Generate a string from shortcode parameters. + +Creates a shortcode instance and returns a string. + +Accepts the same `options` as the `shortcode()` constructor, containing a +`tag` string, a string or object of `attrs`, a boolean indicating whether to +format the shortcode using a `single` tag, and a `content` string. + +**Parameters** + +- **options** `Object`: + +**Returns** + +`string` String representation of the shortcode. + + + +

Code is Poetry.

diff --git a/packages/shortcode/package.json b/packages/shortcode/package.json index acda28244caca8..237baea2d99034 100644 --- a/packages/shortcode/package.json +++ b/packages/shortcode/package.json @@ -25,7 +25,13 @@ "lodash": "^4.17.11", "memize": "^1.0.5" }, + "devDependencies": { + "@wordpress/docgen": "file:../docgen" + }, "publishConfig": { "access": "public" + }, + "scripts": { + "docs:generate": "docgen ./src/index.js --output ./README.md --to-token" } } From 8a41b76e66c11f3a120330467e1d92b12f186508 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Mon, 4 Mar 2019 15:28:51 +0100 Subject: [PATCH 5/7] Use bin script instead of npm script --- bin/generate-docs.sh | 11 +++++++++++ packages/shortcode/package.json | 6 ------ 2 files changed, 11 insertions(+), 6 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 00000000000000..2a43ca7e6799e0 --- /dev/null +++ b/bin/generate-docs.sh @@ -0,0 +1,11 @@ +#!/bin/bash + +declare -a packages=( + "e2e-test-utils" + "shortcode" +) + +for package in "${packages[@]}" +do + npx docgen packages/${package}/src/index.js --output packages/${package}/README.md --to-token; +done diff --git a/packages/shortcode/package.json b/packages/shortcode/package.json index 237baea2d99034..acda28244caca8 100644 --- a/packages/shortcode/package.json +++ b/packages/shortcode/package.json @@ -25,13 +25,7 @@ "lodash": "^4.17.11", "memize": "^1.0.5" }, - "devDependencies": { - "@wordpress/docgen": "file:../docgen" - }, "publishConfig": { "access": "public" - }, - "scripts": { - "docs:generate": "docgen ./src/index.js --output ./README.md --to-token" } } From 8fdbe86e9155000d6edccbd96953a963cb4f56ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Tue, 5 Mar 2019 02:31:46 +0100 Subject: [PATCH 6/7] Use new script --- bin/generate-docs.sh | 11 ----------- bin/update-readmes.js | 2 +- 2 files changed, 1 insertion(+), 12 deletions(-) delete mode 100755 bin/generate-docs.sh diff --git a/bin/generate-docs.sh b/bin/generate-docs.sh deleted file mode 100755 index 2a43ca7e6799e0..00000000000000 --- a/bin/generate-docs.sh +++ /dev/null @@ -1,11 +0,0 @@ -#!/bin/bash - -declare -a packages=( - "e2e-test-utils" - "shortcode" -) - -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 index fb1be92aa4a34b..f874ca000793a5 100755 --- a/bin/update-readmes.js +++ b/bin/update-readmes.js @@ -28,7 +28,7 @@ const packages = [ //'priority-queue', //'redux-routine', 'rich-text', - //'shortcode', + 'shortcode', //'url', //'viewport', //'wordcount', From 7493ed8116141cba517fc59eb1e748383e13e6d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Tue, 5 Mar 2019 12:15:01 +0100 Subject: [PATCH 7/7] Update output --- packages/shortcode/README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/packages/shortcode/README.md b/packages/shortcode/README.md index dc7df6b0b45089..4fc494b224206b 100644 --- a/packages/shortcode/README.md +++ b/packages/shortcode/README.md @@ -38,7 +38,7 @@ or `name=value`. Numeric attributes can be formatted as `"value"` or just **Returns** -`WPShortcodeAttrs` Parsed shortcode attributes. +`WPShortcodeAttrs`: Parsed shortcode attributes. ### default @@ -57,7 +57,7 @@ the `type` of the shortcode ('single', 'self-closing', or 'closed'), and a **Returns** -`WPShortcode` Shortcode instance. +`WPShortcode`: Shortcode instance. ### fromMatch @@ -75,7 +75,7 @@ passed to `regexp.replace()`. **Returns** -`WPShortcode` Shortcode instance. +`WPShortcode`: Shortcode instance. ### next @@ -91,7 +91,7 @@ Find the next matching shortcode. **Returns** -`?WPShortcodeMatch` Matched information. +`?WPShortcodeMatch`: Matched information. ### regexp @@ -118,7 +118,7 @@ Capture groups: **Returns** -`RegExp` Shortcode RegExp. +`RegExp`: Shortcode RegExp. ### replace @@ -134,7 +134,7 @@ Replace matching shortcodes in a block of text. **Returns** -`string` Text with shortcodes replaced. +`string`: Text with shortcodes replaced. ### string @@ -154,7 +154,7 @@ format the shortcode using a `single` tag, and a `content` string. **Returns** -`string` String representation of the shortcode. +`string`: String representation of the shortcode.