Making WordPress.org

Opened 7 years ago

Last modified 6 months ago

#3063 new enhancement

Show JavaScript documentation on developer.wordpress.org

Reported by: atimmer's profile atimmer Owned by:
Milestone: Priority: normal
Component: Developer Hub Keywords:
Cc:

Description

There is a ton of work going into making the JavaScript documentation up to the same standard as the PHP documentation. This is now in a state where we could feasibly add it to developer.wordpress.org.

After https://core.trac.wordpress.org/ticket/41682#comment:7 has been merged the output is useful.

The way the PHP function/method/hook documentation works is by parsing the PHP source code and creating WordPress posts for every symbol. With every WordPress update this process is repeated and the posts are updated. This makes is possible to have user contributed notes and have extra documentation which is edited in a backend meta field.

This would be the way to setup the JavaScript documentation on developer.wordpress.org. The PHP code can be found at https://github.com/wordpress/phpdoc-parser. I have started a JS version on https://github.com/yoast/jsdoc-parser.

I investigated several solutions into parsing the JavaScript source code in WordPress. I tried both https://github.com/documentationjs and https://esdoc.org but both of these have failings. They both have a very hard time handling the JavaScript structure of WordPress core. JSDoc does this much better. And since JSDoc switched to babylon as their JS parser they can handle ES201* very fine now.

Change History (13)

This ticket was mentioned in Slack in #core-js by atimmer. View the logs.


7 years ago

This ticket was mentioned in Slack in #docs by atimmer. View the logs.


7 years ago

#3 @herregroen
6 years ago

I've just made https://github.com/WordPress/phpdoc-parser/pull/207 to update the phpdoc-parser used by developer.wordpress.org to support different languages in order to facilitate this.

This would allow the JSDoc template I've created ( https://github.com/herregroen/jsdoc-parser/ ) to potentially be used to create JSON exports of JSDoc which can then be imported by the phpdoc-parser without risking conflicts where PHP and JS functions have the same name.

Further work would need to be done on the wporg-developer theme to fully support this. Both the new programming language taxonomy as well as the already existing namespace taxonomy would have to be shown much more clearly in the interface.

Next to that the theme currently generates the source code snippets from the local filesystem, which works for WordPress itself but as the Gutenberg source code is still located on GitHub this is also something that would have to be accounted for.

This ticket was mentioned in Slack in #docs by herregroen. View the logs.


6 years ago

#5 @herregroen
6 years ago

Regarding parsing the jsdoc using the JSDoc template I've created you can use the following JSDoc template with Gutenberg. This expects the jsdoc-parser to be located on the same level as the gutenberg directory.

jsdoc.conf.json:

{
  "plugins": [],
  "recurseDepth": 10,
  "source": {
    "include": ["packages/"],
    "exclude": [],
    "includePattern": ".+\\.js(doc|x)?$",
    "excludePattern": "((^|\\/|\\\\)_|node_modules)"
  },
  "sourceType": "module",
  "tags": {
    "allowUnknownTags": true,
    "dictionaries": ["jsdoc","closure"]
  },
  "templates": {
    "packages": true,
    "packagesRoot": "packages/"
  },
  "opts": {
    "template": "../jsdoc-parser",
    "recurse": true
  }
}

Running jsdoc with that configuration ( jsdoc -c jsdoc.conf.json ) will generate a parsed-jsdoc.json file that can be imported using https://github.com/WordPress/phpdoc-parser with the wp parser import command.

This will generate posts in exactly the same manner as is already done for the PHP.

It should be noted that as mentioned above there's a few things lacking in both that plugin as well as the wporg-developer theme that would need to be addressed.

This ticket was mentioned in Slack in #core-js by aduth. View the logs.


6 years ago

This ticket was mentioned in Slack in #docs by herregroen. View the logs.


6 years ago

#8 @oandregal
6 years ago

I've tried this approach on Gutenberg code. Here's the PullRequest I've used as a playground to document my findings with specific code samples from Gutenberg: https://github.com/WordPress/gutenberg/pull/13637

The results weren't what I was expecting so I've tried to tweak it a bit to learn if they could be improved. I don't have a lot of jsdoc experience, so I haven't seen how.

In parallel, I was working on a package to generate Public API docs. Given a ESNext JavaScript file, it outputs a Markdown with its Public API. It takes a different route than this approach: it builds the Abstract Syntax Tree of the code, extracts the export declarations of a given file, and looks backwards from there to find the JSDoc comments up to the declaration. It contains an extensive test suite that hopefully is useful to understand how it works as well. It can be found at https://github.com/WordPress/gutenberg/pull/13329 I've tested it with every Gutenberg package and it works. It seems feasible within a reasonable timeline to improve that package and output a JSON tailored for developer.wordpress.org. From what I've seen, it basically needs to add file references (line numbers, names), and namespaces.

@herregroen @atimmer I was wondering whether you'd take a look at those PullRequests and let me know what do you think?

#9 @oandregal
6 years ago

Herre and I agreed to try the https://github.com/WordPress/gutenberg/pull/13329 approach and see where that takes us.

I'm going to prepare the doc generator to output the necessary information (file name, line numbers) and also to accept a formatter ala jsdoc templates. Herre will use that to create a JSON for developer.wordpress.org and will take care of the integration with our current systems.

Last edited 6 years ago by oandregal (previous) (diff)

This ticket was mentioned in Slack in #core-editor by nosolosw. View the logs.


6 years ago

This ticket was mentioned in Slack in #docs by nosolosw. View the logs.


6 years ago

#12 @oandregal
6 years ago

https://github.com/WordPress/gutenberg/pull/13329 has been merged and it's already generating docs for Gutenberg (embedded in the package's README files at the moment).

The README contains examples and info on how to use it https://github.com/WordPress/gutenberg/tree/master/packages/docgen Please, ping me when you're ready to give it a try for creating the JS docs for core.

This ticket was mentioned in Slack in #core-editor by nosolosw. View the logs.


6 months ago

Note: See TracTickets for help on using tickets.