Like in our old framework:

Context

At Ventures team we would like to generate a hooks document for our internal use and we found there is an awesome script in this repo that just do the things we want. Here's our PR woocommerce/google-listings-and-ads#1573, it basically copy most of the code from the script and then modify a bit to suit what we need.

The Problem

We found the script does not capture all the PHP files in the directory, the TLDR reason is the script cannot work in the case where there are more than two levels of paths. Please see the detailed explanation in our PR's comment: woocommerce/google-listings-and-ads#1573 (comment).

It also relates to #15.

Our solution may not fulfil the needs in this repo, also if there's any better ways to generate hooks documents (like using PHPDoc?) in your mind, we're happy to hear and learn about.

Here's an example:
https://woocommerce.github.io/code-reference/classes/WC-Data.html#property_meta_data

I did a bit of digging, and here are some lines you can see in the HTML files:

It seems like something is interpreting "false" as "\false" and is interpreting "null" as "\null".
https://www.php.net/manual/en/regexp.reference.escape.php

Just like action-build, it would be better to deploy API code reference during the release process via GitHub action.

@claudiosanches For hooks, isn't there an easy process to generate by parsing like previously done in ApiGen context. If some hooks get added then it has to be manually inserted currently right?

I noticed changes in the documentation. This is horrible compared to before. Woocommerce had the best documentation for an open source project. Now everything is an unproductive mess.

@claudiosanches I have tested this repo with PHP 7.2 and received the following error:

Fatal error: Cannot use 'Object' as class name as it is reserved in /var/www/html/apigen/vendor/latte/latte/src/Latte/Object.php on line 14 ErrorException: Cannot use 'Object' as class name as it is reserved in /var/www/html/apigen/vendor/latte/latte/src/Latte/Object.php:14

Currently we are using an old script that doesn't capture all files from our source code.
You can find the current script in https://github.com/woocommerce/code-reference/blob/trunk/generate-hook-docs.php

We could take this opportunity to create a documentation for hooks generating several pages for individual files and types like actions and filters.