Exploration: DocGen custom formatter to raw json and phpdoc-parser json formats #63202
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Warning: Type of PR label mismatch To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.
Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task. |
|
Size Change: 0 B Total Size: 1.76 MB ℹ️ View Unchanged
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Related: #61036
This PR is an exploration for generating the data parsed by
docgenin a JSON format used by WordPress/phpdoc-parser (as one of the steps of the plan of action shared in this comment to get JS functions documented in https://developer.wordpress.org/reference). It provides:update-api-docs-json.jsfile and"docs:api-ref-json": "node ./bin/api-docs/update-api-docs-json.js",script inpackage.jsonupdate-api-docs.jsand"docs:api-ref"script inpackage.jsoncurrently used to generate the parsed API output in markdown filespackages/docgen/lib/json/index.js→ that outputs a raw JSON (directly from the parse output, without further processing) for each one of the files parsed (instead of returning markdown)packages/docgen/lib/phpdoc-parser/index.js→ that outputs a processed JSON for each one of the files parsed, returning the structure expected byphpdoc-parserNOTE: to display
console.login any of the files used in this explorationconst { stdout } = await execa(can be added to this line andconsole.log( stdout );can be added before this lineTo run this exploration, we can do from the root of the repo...
This will generate around 60
.jsonfiles in different locations. For each file parsed, it will generate (in the same location than the file parsed) a.jsonfile with the data parsed bydocgenin a similar.jsonformat than the one used byphpdoc-parserSome notes about this exploration:
phpdoc-parser(see example) has been extracted by storing in a.jsonfile the$outputof itsparse_filesfunction right before this line.jsonfiles intophpdoc-parser(with a local installation usingwporg-developerrepo) didn't work well (final HTML pages with the API reference for JS functions weren't generated) and the errors returned didn't provide much info about where the error was. Some more debugging here would be needed.cc: @oandregal