Skip to content

Exclude command namespaces from README generation #268

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Copilot wants to merge 2 commits into from
Closed

Exclude command namespaces from README generation #268

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5e19c2f
Initial plan
Copilot Jan 10, 2026
0a2eae5
Exclude command namespaces and missing commands from README generation
Copilot Jan 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions features/scaffold-package-readme.feature
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -386,3 +386,46 @@ Feature: Scaffold a README.md file for an existing package
"""
**Alias:** `cpt`
"""

Scenario: README excludes command namespaces
Given an empty directory
And a foo/composer.json file:
"""
{
"name": "wp-cli/namespace-test",
"description": "Test package for excluding command namespaces",
"license": "MIT",
"authors": [],
"minimum-stability": "dev",
"autoload": {
"files": [ "command.php" ]
},
"require": {
"wp-cli/wp-cli": "^2.12"
},
"require-dev": {
"wp-cli/wp-cli-tests": "^5.0.0"
},
"extra": {
"commands": [
"i18n",
"i18n make-pot"
]
}
}
"""

When I run `wp scaffold package-readme foo`
Then the foo/README.md file should exist
And the foo/README.md file should not contain:
"""
### wp i18n
"""
And the foo/README.md file should not contain:
"""
### wp i18n make-pot
"""
And the foo/README.md file should contain:
"""
## Using
"""
19 changes: 18 additions & 1 deletion src/ScaffoldPackageCommand.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -339,16 +339,33 @@ public function package_readme( $args, $assoc_args ) {
}
*/

// Skip commands that were not found or are namespaces with no meaningful content.
if ( false === $parent_command ) {
continue;
}

// Skip command namespaces (commands with subcommands but no meaningful content).
// This needs to be done before processing longdesc to accurately detect empty content.
$has_subcommands = ! empty( $parent_command['subcommands'] );
$shortdesc = isset( $parent_command['description'] ) ? $parent_command['description'] : '';
$raw_longdesc = isset( $parent_command['longdesc'] ) ? $parent_command['longdesc'] : '';
$is_namespace = $has_subcommands && empty( trim( $shortdesc ) ) && empty( trim( $raw_longdesc ) );

if ( $is_namespace ) {
continue;
}

$longdesc = isset( $parent_command['longdesc'] ) ? $parent_command['longdesc'] : '';
$longdesc = (string) preg_replace( '/## GLOBAL PARAMETERS(.+)/s', '', $longdesc );
$longdesc = (string) preg_replace( '/##\s(.+)/', '**$1**', $longdesc );

// definition lists
$longdesc = preg_replace_callback( '/([^\n]+)\n: (.+?)(\n\n|$)/s', [ __CLASS__, 'rewrap_param_desc' ], $longdesc );

$shortdesc = isset( $parent_command['description'] ) ? $parent_command['description'] : '';
$command_data = [
'name' => "wp {$command}",
'shortdesc' => isset( $parent_command['description'] ) ? $parent_command['description'] : '',
'shortdesc' => $shortdesc,
'synopsis' => "wp {$command}" . ( empty( $parent_command['subcommands'] ) ? ( isset( $parent_command['synopsis'] ) ? " {$parent_command['synopsis']}" : '' ) : '' ),
'longdesc' => $longdesc,
];
Expand Down