Document WordPress filters and actions
Closed this issue · 2 comments
WooCoomerce
WooCoomerce is using a PHP script to document their WordPress filters and actions:
https://github.com/woocommerce/code-reference/blob/0.7.0/generate-hook-docs.php
It extends https://www.phpdoc.org/ documentation by replacing the text <!-- hooks --> in the generated phpDocumentor output files: https://github.com/woocommerce/code-reference/blob/0.7.0/generate-hook-docs.php#L333.
https://woocommerce.github.io/code-reference/
ApiGen
Before June 2019, WooCommerce used ApiGen:
https://github.com/woocommerce/woocommerce/pull/24003/files
The ApiGen documentation was removed somewhere between WooCommerce version 3.6.0 and 3.7.0: https://github.com/woocommerce/woocommerce/tree/3.6.0/apigen. This documentation was also extended with the hooks / actions information via a PHP script: https://github.com/woocommerce/woocommerce/blob/3.6.0/apigen/hook-docs.php. It also had a "Direct known implementers" and "Indirect known implementers" sections, which are not yet available in the phpDocumentor documentation: woocommerce/code-reference#11.
WP Parser
The WordPress Code Reference on https://developer.wordpress.org/reference/ is generated using https://github.com/WordPress/phpdoc-parser, more information about this can be found at https://make.wordpress.org/docs/handbook/devhub/. This libary/plugin contains WP-CLI commands to export PHPDoc markup to JSON and convert it into WordPress posts, and insert into DB.
WordPress HookDoc
An alternative is to use https://github.com/matzeeable/wp-hookdoc which uses https://github.com/jsdoc/jsdoc.
GitHub Actions for WordPress
In https://github.com/10up/actions-wordpress#ideas the following idea is described:
Generate hook docs into a Markdown file that can be published into a subfolder, GitHub wiki, and/or gh-pages branch.
This idea was added by @helen almost 2 years ago:
10up/actions-wordpress@556d7a6
Update April 4, 2021
This idea has already been realized, see:
https://github.com/10up/actions-wordpress/blob/stable/hookdocs-workflow.md
Example
- https://github.com/10up/distributor/blob/develop/.github/workflows/build-docs.yml
- https://10up.github.io/distributor/
Hookster
Thinking about making a developer docs website for your WordPress theme or plugin? For my weekend project, I made a build script for theme/plugin authors to automatically generate data about all the actions and filters of their product.
https://twitter.com/jasonbobich/status/987836700989669376
https://github.com/themeblvd/hookster
Yoast Parser
- phpDocumentor / Reflection » Issue "Extracting WordPress hooks from source"
- Gist » jcomack/FileVisitor.php
- https://github.com/Yoast/code-documentation-extractor
phpDox
Other Plugins
There are also many other plugins that have documentation for their filters and actions:
Hi! Looks like I need to update the develop branch but we do have hook docs via GH Actions working! https://github.com/10up/actions-wordpress/blob/stable/hookdocs-workflow.md
We developed https://github.com/pronamic/wp-documentor for this, see as output: https://github.com/wp-pay/core/blob/develop/docs/hooks.md.
@helen maybe is https://github.com/pronamic/wp-documentor also something for 10up 😊? The advantages of https://github.com/pronamic/wp-documentor are that you do not have to add the @hook tag or put the types between curly brackets (for example: {int}, {string}, etc.).