Documenting WordPress hooks (filters and actions) #2865

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?

pronamic/wp-pay-core#45