Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add "components" docs #8337

Merged
merged 18 commits into from
Aug 8, 2018
Merged

Add "components" docs #8337

Show file tree
Hide file tree
Changes from 9 commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
f4e76a8
Auto-generate components documentation manifest
wpscholar Jul 31, 2018
45d64fe
Ensure that the packages root doc is defined immediately before its c…
wpscholar Jul 31, 2018
6e6abd8
Ran `npm run docs:build`
wpscholar Jul 31, 2018
4d95a66
Automated build of docs based on changes to the `root-manifest.json` …
wpscholar Jul 31, 2018
c682113
Ensure that `packages/*/README.md` file changes also trigger docs gen…
wpscholar Aug 1, 2018
25dc1a2
Rename `Components` parent title to `Components Package Reference`
wpscholar Aug 1, 2018
e31f561
Ensure that `Packages` shows first, then `Data Package Reference`, th…
wpscholar Aug 1, 2018
1264078
Automatically ran `npm run docs:build`
wpscholar Aug 1, 2018
7bb46f3
Merge branch 'master' into add/components-docs
wpscholar Aug 1, 2018
cbc846f
Merge branch 'master' into add/components-docs
wpscholar Aug 7, 2018
34db1da
Split up manifest.js into separate functions and removed code that ge…
wpscholar Aug 7, 2018
c2287a9
Merge branch 'master' into add/components-docs
gziolo Aug 8, 2018
260cb62
Update package-lock.json
gziolo Aug 8, 2018
9ee1205
Update data-core.md
gziolo Aug 8, 2018
2ab9aa0
Update manifest.json
gziolo Aug 8, 2018
e4c90e6
Update data-core-editor.md
gziolo Aug 8, 2018
e2814c2
Update manifest.json
gziolo Aug 8, 2018
7897de5
Merge branch 'master' into add/components-docs
gziolo Aug 8, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/data/data-core-editor.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1435,4 +1435,4 @@ Returns an action object used in signalling that the editor settings have been u

*Parameters*

* settings: Updated settings
* settings: Updated settings
198 changes: 198 additions & 0 deletions docs/manifest.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -496,5 +496,203 @@
"slug": "data-core-viewport",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/data/data-core-viewport.md",
"parent": "data"
},
{
"title": "Components Package Reference",
"slug": "components",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components.md",
"parent": null
},
{
"title": "Autocomplete",
"slug": "autocomplete",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/autocomplete/README.md",
"parent": "components"
},
{
"title": "BaseControl",
"slug": "base-control",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/base-control/README.md",
"parent": "components"
},
{
"title": "Button",
"slug": "button",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/button/README.md",
"parent": "components"
},
{
"title": "CheckboxControl",
"slug": "checkbox-control",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/checkbox-control/README.md",
"parent": "components"
},
{
"title": "DateTime",
"slug": "date-time",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/date-time/README.md",
"parent": "components"
},
{
"title": "Disabled",
"slug": "disabled",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/disabled/README.md",
"parent": "components"
},
{
"title": "Draggable",
"slug": "draggable",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/draggable/README.md",
"parent": "components"
},
{
"title": "DropZone",
"slug": "drop-zone",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/drop-zone/README.md",
"parent": "components"
},
{
"title": "DropdownMenu",
"slug": "dropdown-menu",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/dropdown-menu/README.md",
"parent": "components"
},
{
"title": "Dropdown",
"slug": "dropdown",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/dropdown/README.md",
"parent": "components"
},
{
"title": "FocusableIframe",
"slug": "focusable-iframe",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/focusable-iframe/README.md",
"parent": "components"
},
{
"title": "FontSizePicker",
"slug": "font-size-picker",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/font-size-picker/README.md",
"parent": "components"
},
{
"title": "FormTokenField",
"slug": "form-token-field",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/form-token-field/README.md",
"parent": "components"
},
{
"title": "HigherOrder",
"slug": "higher-order",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/higher-order/README.md",
"parent": "components"
},
{
"title": "KeyboardShortcuts",
"slug": "keyboard-shortcuts",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/keyboard-shortcuts/README.md",
"parent": "components"
},
{
"title": "Modal",
"slug": "modal",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/modal/README.md",
"parent": "components"
},
{
"title": "NavigableContainer",
"slug": "navigable-container",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/navigable-container/README.md",
"parent": "components"
},
{
"title": "Notice",
"slug": "notice",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/notice/README.md",
"parent": "components"
},
{
"title": "Popover",
"slug": "popover",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/popover/README.md",
"parent": "components"
},
{
"title": "RadioControl",
"slug": "radio-control",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/radio-control/README.md",
"parent": "components"
},
{
"title": "RangeControl",
"slug": "range-control",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/range-control/README.md",
"parent": "components"
},
{
"title": "Sandbox",
"slug": "sandbox",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/sandbox/README.md",
"parent": "components"
},
{
"title": "ScrollLock",
"slug": "scroll-lock",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/scroll-lock/README.md",
"parent": "components"
},
{
"title": "SelectControl",
"slug": "select-control",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/select-control/README.md",
"parent": "components"
},
{
"title": "ServerSideRender",
"slug": "server-side-render",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/server-side-render/README.md",
"parent": "components"
},
{
"title": "SlotFill",
"slug": "slot-fill",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/slot-fill/README.md",
"parent": "components"
},
{
"title": "TabPanel",
"slug": "tab-panel",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/tab-panel/README.md",
"parent": "components"
},
{
"title": "TextControl",
"slug": "text-control",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/text-control/README.md",
"parent": "components"
},
{
"title": "TextareaControl",
"slug": "textarea-control",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/textarea-control/README.md",
"parent": "components"
},
{
"title": "ToggleControl",
"slug": "toggle-control",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/toggle-control/README.md",
"parent": "components"
},
{
"title": "Tooltip",
"slug": "tooltip",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/tooltip/README.md",
"parent": "components"
},
{
"title": "TreeSelect",
"slug": "tree-select",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/tree-select/README.md",
"parent": "components"
}
]
6 changes: 0 additions & 6 deletions docs/root-manifest.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -208,11 +208,5 @@
"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
}
]
24 changes: 22 additions & 2 deletions docs/tool/config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,17 @@
*/
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is meant to be a "config" file, I'd personally move all the logic to generate the manifest to docs/tool/manifest.js and leave here only the parts that are "configurable"

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess the line is not always easy to draw. We should probably rethink this config globally though. So don't take this comment as a big blocker.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is what I was going to do initially, but that file exports a single function that is very specific to the logic for the packages and data docs. I considered exporting an object from that file which contained more than one function but went the path of least resistance. I'd be happy to make some changes if you have a specific recommendation.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since the function is already doing two things, it can do three :) and we can split it into three functions if necessary.

I'd only keep 'packages/components/src' as a config variable. Something like: componentsSource or something like that, and just move everything else to manifest.js.

Also it looks like the baseRepoUrl is already being used in that file (hardcoded), so it might be good to use this variable consistently.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's address this feedback and 🚢

I really like the automation proposed in this PR 💯

const glob = require( 'glob' ).sync;
const path = require( 'path' );
const { upperFirst, camelCase } = require( 'lodash' );

const root = path.resolve( __dirname, '../../' );

const baseRepoUrl = `https://raw.githubusercontent.com/WordPress/gutenberg/master/`;

// These are packages published to NPM as their own node modules.
const npmReadyPackages = glob( 'packages/*/package.json' )
.map( ( fileName ) => fileName.split( '/' )[ 1 ] );

// These are internal-only packages (for now), not yet published as standalone
// node modules.
// These are internal-only packages (for now), not yet published as standalone node modules.
const gutenbergPackages = [
'core-blocks',
'edit-post',
Expand Down Expand Up @@ -65,5 +67,23 @@ module.exports = {
},

rootManifest: path.resolve( __dirname, '../root-manifest.json' ),
componentsManifest: [
{
title: 'Components Package Reference',
slug: 'components',
markdown_source: `${ baseRepoUrl }packages/components.md`,
parent: null,
},
...glob( 'packages/components/src/*/README.md' )
.map( ( filePath ) => {
const slug = filePath.split( '/' )[ 3 ];
return {
title: upperFirst( camelCase( slug ) ),
slug,
markdown_source: `${ baseRepoUrl }${ filePath }`,
parent: 'components',
};
} ),
],
manifestOutput: path.resolve( __dirname, '../manifest.json' ),
};
2 changes: 1 addition & 1 deletion docs/tool/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,5 +18,5 @@ const dataModuleManifest = getManifest( parsedModules, config.packages );

fs.writeFileSync(
config.manifestOutput,
JSON.stringify( rootManifest.concat( dataModuleManifest ), undefined, '\t' )
JSON.stringify( rootManifest.concat( dataModuleManifest, config.componentsManifest ), undefined, '\t' )
);
31 changes: 20 additions & 11 deletions docs/tool/manifest.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,17 +29,26 @@ module.exports = function( parsedNamespaces, packagesConfig ) {
} )
);

const packagesManifest = Object.entries( packagesConfig ).map( ( [ folderName, config ] ) => {
const path = config.isNpmReady === false ?
`https://raw.githubusercontent.com/WordPress/gutenberg/master/${ folderName }/README.md` :
`https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/${ folderName }/README.md`;
return {
title: `@wordpress/${ folderName }`,
slug: `packages-${ folderName }`,
markdown_source: path,
parent: 'packages',
};
} );
const packagesManifest = [
{
title: 'Packages',
slug: 'packages',
markdown_source: 'https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/packages.md',
parent: null,
},
].concat(
Object.entries( packagesConfig ).map( ( [ folderName, config ] ) => {
const path = config.isNpmReady === false ?
`https://raw.githubusercontent.com/WordPress/gutenberg/master/${ folderName }/README.md` :
`https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/${ folderName }/README.md`;
return {
title: `@wordpress/${ folderName }`,
slug: `packages-${ folderName }`,
markdown_source: path,
parent: 'packages',
};
} )
);

return packagesManifest.concat( dataManifest );
};
Loading