Documentation: Generates the manifest dynamically to include the data module docs in the handbook #7411
Conversation
… module docs in the handbook
youknowriad
added
the
[Type] Developer Documentation
There was a problem hiding this comment.
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.
docs/manifest.json
Outdated
| "parent": "outreach" | ||
| } | ||
| ] | ||
| { |
There was a problem hiding this comment.
Just noting that this generated file has different whitespsce style. Is there an easy way to fix it?
docs/manifest.json
Outdated
| @@ -1,212 +1,254 @@ | |||
| [ | |||
There was a problem hiding this comment.
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 😃
There was a problem hiding this comment.
Unfortunately, comments are not allowed in JSON?
docs/tool/manifest.js
Outdated
| /** | ||
| * Node dependencies | ||
| */ | ||
| const lodash = require( 'lodash' ); |
There was a problem hiding this comment.
Nit: This file could use object destructuring for lodash method 😎
docs/manifest.json
Outdated
| { | ||
| "title": "Data Package Reference", | ||
| "slug": "packages-data", | ||
| "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/data/index.md", |
There was a problem hiding this comment.
Can this file be renamed to README.md to enable the default GitHub support in the browser when browsing repository?
| @@ -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", | |||
There was a problem hiding this comment.
We have both docs:build and build:packages scripts. We should be consistent with our naming.
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.jsoncontaining 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 :)