Documenting WordPress hooks (filters and actions) #2865
Description
I am researching how we can document WordPress filters and actions with phpDocumentor, for example:
<?php
/**
* This is a well documented action.
*
* Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
* Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
*
* @since 2.9.0
*
* @param string $option Name of the option to update.
* @param mixed $old_value The old option value.
* @param mixed $value The new option value.
*/
do_action('good_doc_static_action', $option, $old_value, $value);https://github.com/WordPress/phpdoc-parser/blob/master/tests/source/actions.php
I have found that WooCommerce extends the phpDocumenter output with a custom script and a string replace call:
- https://github.com/woocommerce/code-reference/blob/0.7.0/data/templates/woocommerce/hooks/hooks.html.twig
- https://github.com/woocommerce/code-reference/blob/0.7.0/generate-hook-docs.php#L317-L346
- https://woocommerce.github.io/code-reference/hooks/hooks.html
Automattic / WooCommerce is using a custom phpDocumentor template for this:
https://github.com/woocommerce/code-reference/tree/0.7.0/data/templates/woocommerce
I would like to use the default phpDocumentor template:
https://github.com/phpDocumentor/phpDocumentor/tree/v3.0.0/data/templates/default
Is there a way to extend default phpDocumentor template output? Based on the documentation and the code, I could not find out if this is possible. But this may also be because I'm not very familiar with Twig (https://twig.symfony.com/). And from the documentation it is also not very clear to me if and how the <transformations> / <transformation> can be used for this. I noticed that the documentation needs some love: #2063, some examples would be great.
I have also tried to see if the experimental 'Guides' functionality can be used for this. I figured out that it is quite easy to create for example an 'Actions' and 'Filters' page. But I was unable to expand these pages with extra 'dynamic' information. I am also not familiar with reStructuredText, but came across the concept of directives: https://docutils.sourceforge.io/docs/ref/rst/directives.html. Is there maybe a way to register / define custom reStructuredText directives? For example a directive wp-actions and wp-filters that we can parse/transform into a table/list?
See for an example:
- https://github.com/pronamic/wp-http/blob/main/phpdoc.dist.xml
- https://github.com/pronamic/wp-http/blob/main/docs/actions.rst » https://pronamic.github.io/wp-http/guide/actions.html
- https://github.com/pronamic/wp-http/blob/main/docs/filters.rst » https://pronamic.github.io/wp-http/guide/filters.html
I would like to create something similar to: https://woocommerce.github.io/code-reference/hooks/hooks.html. For WordPress developers it would be great if there is an easy way to extend the phpDocumentor with the WordPress filters / actions documentation. Or is it more convenient to do this outside of phpDocumentor and, for example, build a WordPress actions / filters documentation site with Jekyll?