Error regenerating doc pages
ernilambar opened this issue · comments
Bug Report
- Yes, I reviewed the contribution guidelines.
- Yes, more specifically, I reviewed the guidelines on how to write clear bug reports.
Describe the current, buggy behavior
When I follow the steps given in https://github.com/wp-cli/handbook#wp-clihandbook there are lots of PHP notices and warnings. All the files in the internal-api are deleted.
Describe how other contributors can replicate this bug
- wp cli update --nightly
- bin/install_packages.sh
- WP_CLI_SUPPRESS_GLOBAL_PARAMS=false WP_CLI_PACKAGES_DIR=bin/packages WP_CLI_CONFIG_PATH=/dev/null wp handbook gen-all
Describe what you would expect as the correct outcome
Pages should be regenerated properly.
Let us know what environment you are running this on
OS: Darwin 22.6.0 Darwin Kernel Version 22.6.0: Tue Nov 7 21:48:06 PST 2023; root:xnu-8796.141.3.702.9~2/RELEASE_X86_64 x86_64
Shell: /bin/zsh
PHP binary: /usr/local/Cellar/php@8.2/8.2.18/bin/php
PHP version: 8.2.18
php.ini used: /usr/local/etc/php/8.2/php.ini
MySQL binary: /usr/local/mysql-8.0.36-macos14-x86_64/bin/mysql
MySQL version: mysql Ver 8.0.36 for macos14 on x86_64 (MySQL Community Server - GPL)
SQL modes:
WP-CLI root dir: phar://wp-cli.phar/vendor/wp-cli/wp-cli
WP-CLI vendor dir: phar://wp-cli.phar/vendor
WP_CLI phar path: /Users/nilambarsharma/Code/kli/handbook
WP-CLI packages dir: /Users/nilambarsharma/.wp-cli/packages/
WP-CLI cache dir: /Users/nilambarsharma/.wp-cli/cache
WP-CLI global config:
WP-CLI project config: /Users/nilambarsharma/Code/kli/handbook/wp-cli.yml
WP-CLI version: 2.11.0-alpha-c661c45
Provide additional context/Screenshots
...
PHP Warning: Undefined array key 1 in /Users/nilambarsharma/Code/kli/handbook/bin/command.php on line 623
PHP Warning: Undefined array key 1 in /Users/nilambarsharma/Code/kli/handbook/bin/command.php on line 623
PHP Warning: Undefined array key 1 in /Users/nilambarsharma/Code/kli/handbook/bin/command.php on line 623
PHP Warning: Undefined array key 1 in /Users/nilambarsharma/Code/kli/handbook/bin/command.php on line 623
PHP Warning: Undefined array key 1 in /Users/nilambarsharma/Code/kli/handbook/bin/command.php on line 623
PHP Warning: Undefined array key 1 in /Users/nilambarsharma/Code/kli/handbook/bin/command.php on line 623
PHP Warning: Undefined array key 1 in /Users/nilambarsharma/Code/kli/handbook/bin/command.php on line 623
PHP Warning: foreach() argument must be of type array|object, null given in /Users/nilambarsharma/Code/kli/handbook/bin/command.php on line 78
Warning: foreach() argument must be of type array|object, null given in /Users/nilambarsharma/Code/kli/handbook/bin/command.php on line 78
Removed existing contents of '/Users/nilambarsharma/Code/kli/handbook/internal-api/'
Success: Generated internal-api/
Removed existing contents of '/Users/nilambarsharma/Code/kli/handbook/commands/'
Success: Generated all command pages.
Success: Generated bin/commands-manifest.json of 423 commands
Success: Generated bin/handbook-manifest.json
Success: Generated all doc pages.
I dug little deep into this issue. Our main issue here starts from the handbook api-dump command. There are lots of PHP notices in the command output. So the result is not partiucularly valid JSON output. Output of this command is used in gen-all command. This gen-all deletes the internal-api folder and tries to regenerate all markdown file but could not due to invalid JSON result from the above function.
Error is coming around this line - https://github.com/wp-cli/handbook/blob/main/bin/command.php#L622
preg_match( '/@(\w+)/', $info, $matches );
$param_name = $matches[1];
We have assumed here that there will always be match and $matches[1] is used directly without conditional. So, I am not sure since when this error started.
I checked the git blame but it seems these lines have not been changed since 7 years.
Also in public function gen_api_docs() method, we have assumed that the output of the command is always valid JSON and used directly. May be we need some sanity check in this method also.
Aside: We really need to add some tests here in this repo.