From 654f30fd21bb39042d173d9dcddf9e1e19e6db67 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Fri, 29 Jun 2018 12:26:19 +0100 Subject: [PATCH 1/4] Documentation: Adding the packages READMEs to the handbook --- docs/manifest.json | 138 ++++++++++++++++++++++++++++++++++++++++ docs/packages.md | 11 ++++ docs/root-manifest.json | 6 ++ docs/tool/config.js | 41 +++++++++++- docs/tool/index.js | 2 +- docs/tool/manifest.js | 19 +++++- 6 files changed, 212 insertions(+), 5 deletions(-) create mode 100644 docs/packages.md diff --git a/docs/manifest.json b/docs/manifest.json index a59175c04ac40..3a3c4a94eab39 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -209,6 +209,144 @@ "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/outreach/resources.md", "parent": "outreach" }, + { + "title": "Packages", + "slug": "packages", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/packages.md", + "parent": null + }, + { + "title": "@wordpress/api-request", + "slug": "packages-api-request", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/api-request/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/babel-plugin-import-jsx-pragam", + "slug": "packages-babel-plugin-import-jsx-pragam", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/babel-plugin-import-jsx-pragam/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/blob", + "slug": "packages-blob", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/blob/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/core-data", + "slug": "packages-core-data", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/core-data/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/data", + "slug": "packages-data", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/data/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/date", + "slug": "packages-date", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/date/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/deprecated", + "slug": "packages-deprecated", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/deprecated/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/dom", + "slug": "packages-dom", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/dom/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/element", + "slug": "packages-element", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/element/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/keycodes", + "slug": "packages-keycodes", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/keycodes/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/library-export-default-webpack-plugin", + "slug": "packages-library-export-default-webpack-plugin", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/library-export-default-webpack-plugin/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/plugins", + "slug": "packages-plugins", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/plugins/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/postcss-themes", + "slug": "packages-postcss-themes", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/postcss-themes/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/shortcode", + "slug": "packages-shortcode", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/shortcode/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/blocks", + "slug": "packages-blocks", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/blocks/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/components", + "slug": "packages-components", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/components/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/core-blocks", + "slug": "packages-core-blocks", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/core-blocks/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/edit-post", + "slug": "packages-edit-post", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/edit-post/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/editor", + "slug": "packages-editor", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/editor/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/nux", + "slug": "packages-nux", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/nux/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/utils", + "slug": "packages-utils", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/utils/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/viewport", + "slug": "packages-viewport", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/viewport/README.md", + "parent": "packages" + }, { "title": "Data Package Reference", "slug": "data", diff --git a/docs/packages.md b/docs/packages.md new file mode 100644 index 0000000000000..ac767e389d18c --- /dev/null +++ b/docs/packages.md @@ -0,0 +1,11 @@ +# packages + +Gutenberg exposes a list of JavaScript packages and tools for WordPress development. + +## Using the packages + +JavaScript packages are available as a registered script in WordPress and can be accessed using the `wp` global variable. + +All the packages are also available on [npm](https://www.npmjs.com/org/wordpress) if you want to bundle them in your code. + +

Code is Poetry.

\ No newline at end of file diff --git a/docs/root-manifest.json b/docs/root-manifest.json index a6ba988310e3a..6707b70d8e7a8 100644 --- a/docs/root-manifest.json +++ b/docs/root-manifest.json @@ -208,5 +208,11 @@ "slug": "resources", "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/outreach\/resources.md", "parent": "outreach" + }, + { + "title": "Packages", + "slug": "packages", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/packages.md", + "parent": null } ] diff --git a/docs/tool/config.js b/docs/tool/config.js index 3c608e69a3186..a72c310ef7f44 100644 --- a/docs/tool/config.js +++ b/docs/tool/config.js @@ -5,6 +5,34 @@ const path = require( 'path' ); const root = path.resolve( __dirname, '../../' ); +const npmReadyPackages = [ + 'api-request', + 'babel-plugin-import-jsx-pragam', + 'blob', + 'core-data', + 'data', + 'date', + 'deprecated', + 'dom', + 'element', + 'keycodes', + 'library-export-default-webpack-plugin', + 'plugins', + 'postcss-themes', + 'shortcode', +]; + +const gutenbergPackages = [ + 'blocks', + 'components', + 'core-blocks', + 'edit-post', + 'editor', + 'nux', + 'utils', + 'viewport', +]; + module.exports = { dataNamespaces: { core: { @@ -39,10 +67,19 @@ module.exports = { actions: [ path.resolve( root, 'nux/store/actions.js' ) ], }, }, - dataDocsOutput: path.resolve( __dirname, '../data' ), - rootManifest: path.resolve( __dirname, '../root-manifest.json' ), + packages: { + ...npmReadyPackages.reduce( ( memo, pkg ) => { + memo[ pkg ] = { isNpmReady: true }; + return memo; + }, {} ), + ...gutenbergPackages.reduce( ( memo, pkg ) => { + memo[ pkg ] = { isNpmReady: false }; + return memo; + }, {} ), + }, + rootManifest: path.resolve( __dirname, '../root-manifest.json' ), manifestOutput: path.resolve( __dirname, '../manifest.json' ), }; diff --git a/docs/tool/index.js b/docs/tool/index.js index 33f2331e402cd..9f6d752dd224a 100644 --- a/docs/tool/index.js +++ b/docs/tool/index.js @@ -14,7 +14,7 @@ const getManifest = require( './manifest' ); const parsedModules = parser( config.dataNamespaces ); generator( parsedModules, config.dataDocsOutput ); const rootManifest = require( config.rootManifest ); -const dataModuleManifest = getManifest( parsedModules ); +const dataModuleManifest = getManifest( parsedModules, config.packages ); fs.writeFileSync( config.manifestOutput, diff --git a/docs/tool/manifest.js b/docs/tool/manifest.js index 87554033a0ae7..7ea3c2a5ee377 100644 --- a/docs/tool/manifest.js +++ b/docs/tool/manifest.js @@ -7,11 +7,12 @@ const { kebabCase } = require( 'lodash' ); * Generates the manifest for the given namespaces. * * @param {Object} parsedNamespaces Parsed Namespace Object. + * @param {Object} packagesConfig Packages Docs Config. * * @return {Array} manifest. */ -module.exports = function( parsedNamespaces ) { - return [ { +module.exports = function( parsedNamespaces, packagesConfig ) { + const dataManifest = [ { title: 'Data Package Reference', slug: 'data', markdown_source: 'https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/data/README.md', @@ -27,4 +28,18 @@ module.exports = function( parsedNamespaces ) { }; } ) ); + + const packagesManifest = Object.entries( packagesConfig ).map( ( [ packageSlug, config ] ) => { + const path = config.isNpmReady === false ? + 'https://raw.githubusercontent.com/WordPress/gutenberg/master/' + packageSlug + '/README.md' : + 'https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/' + packageSlug + '/README.md'; + return { + title: '@wordpress/' + packageSlug, + slug: 'packages-' + packageSlug, + markdown_source: path, + parent: 'packages', + }; + } ); + + return packagesManifest.concat( dataManifest ); }; From 41d33d64e672ed4ca640f5018ab84d67f909bf86 Mon Sep 17 00:00:00 2001 From: "Matthew Riley MacPherson (tofumatt)" Date: Fri, 29 Jun 2018 13:05:48 +0100 Subject: [PATCH 2/4] chore: Use packageName instead of pkg --- docs/tool/config.js | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/tool/config.js b/docs/tool/config.js index a72c310ef7f44..604a2ef0e43e3 100644 --- a/docs/tool/config.js +++ b/docs/tool/config.js @@ -70,12 +70,12 @@ module.exports = { dataDocsOutput: path.resolve( __dirname, '../data' ), packages: { - ...npmReadyPackages.reduce( ( memo, pkg ) => { - memo[ pkg ] = { isNpmReady: true }; + ...npmReadyPackages.reduce( ( memo, packageName ) => { + memo[ packageName ] = { isNpmReady: true }; return memo; }, {} ), - ...gutenbergPackages.reduce( ( memo, pkg ) => { - memo[ pkg ] = { isNpmReady: false }; + ...gutenbergPackages.reduce( ( memo, packageName ) => { + memo[ packageName ] = { isNpmReady: false }; return memo; }, {} ), }, From ae3f850dac1cd72138e0139ba85c146cd5515246 Mon Sep 17 00:00:00 2001 From: "Matthew Riley MacPherson (tofumatt)" Date: Fri, 29 Jun 2018 13:08:01 +0100 Subject: [PATCH 3/4] chore: Use template strings --- docs/tool/manifest.js | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/tool/manifest.js b/docs/tool/manifest.js index 7ea3c2a5ee377..b73e36d2f6d84 100644 --- a/docs/tool/manifest.js +++ b/docs/tool/manifest.js @@ -22,8 +22,8 @@ module.exports = function( parsedNamespaces, packagesConfig ) { const slug = kebabCase( parsedNamespace.name ); return { title: parsedNamespace.title, - slug: 'data-' + slug, - markdown_source: 'https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/data/' + slug + '.md', + slug: `data-${ slug }`, + markdown_source: `https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/data/${ slug }.md`, parent: 'data', }; } ) @@ -31,11 +31,11 @@ module.exports = function( parsedNamespaces, packagesConfig ) { const packagesManifest = Object.entries( packagesConfig ).map( ( [ packageSlug, config ] ) => { const path = config.isNpmReady === false ? - 'https://raw.githubusercontent.com/WordPress/gutenberg/master/' + packageSlug + '/README.md' : - 'https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/' + packageSlug + '/README.md'; + `https://raw.githubusercontent.com/WordPress/gutenberg/master/${ packageSlug }/README.md` : + `https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/${ packageSlug }/README.md`; return { - title: '@wordpress/' + packageSlug, - slug: 'packages-' + packageSlug, + title: `@wordpress/${ packageSlug }`, + slug: `packages-${ packageSlug }`, markdown_source: path, parent: 'packages', }; From 7bb143fb22a8c638525c287b424220d63dcce998 Mon Sep 17 00:00:00 2001 From: "Matthew Riley MacPherson (tofumatt)" Date: Fri, 29 Jun 2018 13:10:23 +0100 Subject: [PATCH 4/4] docs: Clarify what an npmReady package means --- docs/tool/config.js | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/tool/config.js b/docs/tool/config.js index 604a2ef0e43e3..e3e2011efbd20 100644 --- a/docs/tool/config.js +++ b/docs/tool/config.js @@ -5,6 +5,7 @@ const path = require( 'path' ); const root = path.resolve( __dirname, '../../' ); +// These are packages published to NPM as their own node modules. const npmReadyPackages = [ 'api-request', 'babel-plugin-import-jsx-pragam', @@ -22,6 +23,8 @@ const npmReadyPackages = [ 'shortcode', ]; +// These are internal-only packages (for now), not yet published as standalone +// node modules. const gutenbergPackages = [ 'blocks', 'components',