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.

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

Documentation: Generates the manifest dynamically to include the data module docs in the handbook #7411

Merged
merged 4 commits into from Jun 28, 2018

Conversation

Projects
None yet
3 participants
@youknowriad
Contributor

youknowriad commented Jun 20, 2018

I'm not certain the Handbook supports more than one level of nesting in the menu because this PR uses two level. If it's not we can update it to move the Data Module Menu Item to the root level.

This PR includes a build step to generate the manifest.json by concatenating the root-manifest.json containing the static docs with the manifest generated by parsing the data module selectors/actions.

Not certain how I can test the result, if everything is working as expected. Some help needed here @pento :)

@youknowriad youknowriad self-assigned this Jun 20, 2018

@youknowriad youknowriad requested review from pento, mtias, gziolo and aduth Jun 20, 2018

@gziolo

gziolo approved these changes Jun 28, 2018

Great job on providing docs for data parts. I love this because it makes it easier to generate more sections like this. My next immediate use case would be to offer a section for packages.

There is one improvement to consider:

  • Add comments to all generated files to make it clear that they were auto-generated with link to the original file.

It still needs to be confirmed that we can have 2 levels of nesting for sections in Gutenberg hsndbook, otherwise we should promote it to its own section.

"parent": "outreach"
}
]
{

This comment has been minimized.

@gziolo

gziolo Jun 28, 2018

Member

Just noting that this generated file has different whitespsce style. Is there an easy way to fix it?

@@ -1,212 +1,254 @@
[

This comment has been minimized.

@gziolo

gziolo Jun 28, 2018

Member

Can we add a comment at the top of this file explaining that it was auto-generated? I bet someone will update it manually soon 😃

This comment has been minimized.

@youknowriad

youknowriad Jun 28, 2018

Contributor

Unfortunately, comments are not allowed in JSON?

This comment has been minimized.

@gziolo
/**
* Node dependencies
*/
const lodash = require( 'lodash' );

This comment has been minimized.

@gziolo

gziolo Jun 28, 2018

Member

Nit: This file could use object destructuring for lodash method 😎

{
"title": "Data Package Reference",
"slug": "packages-data",
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/data/index.md",

This comment has been minimized.

@gziolo

gziolo Jun 28, 2018

Member

Can this file be renamed to README.md to enable the default GitHub support in the browser when browsing repository?

@youknowriad youknowriad merged commit 41be78b into master Jun 28, 2018

2 checks passed

codecov/project 47.26% (+0.39%) compared to 657c368
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details

@youknowriad youknowriad deleted the try/generate-docs-manifest branch Jun 28, 2018

@@ -150,7 +150,7 @@
"predev": "npm run check-engines",
"dev": "npm run build:packages && concurrently \"cross-env webpack --watch\" \"npm run dev:packages\"",
"dev:packages": "node ./bin/packages/watch.js",
"docs:generate-data-reference": "node docs/data/tool",
"docs:build": "node docs/tool",

This comment has been minimized.

@aduth

aduth Jul 17, 2018

Member

We have both docs:build and build:packages scripts. We should be consistent with our naming.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment