Automate regeneration of README file for bundled commands

[schlessera]

As already discussed, the regeneration of the README.md file after a code change adds an unnecessary burden to contributors.

I suggest the following changes to each bundled command to remove this additional step:

• Add wp-cli/scaffold-package-command as a dev requirement.
• Add a pre-commit hook that runs wp scaffold package-readme . --force before committing code changes.
• Add the following lines to the .gitattributes file to remove the README.md file from git diff output and have it show up as a hidden generated file in GitHub pull requests:

  README.md    -diff merge=ours
  README.md    linguist-generated=true

[schlessera]

This is being worked on through https://github.com/wp-cli/regenerate-readme.

[bukowa]

I suggest exporting all commands into json, something similiar like below but with better structure, for example:

{
    "Name": "wp",
    "Description": "...",
    "Subcommands": [
        {
            "core": "...",
            "cache": "...",
        }
    ]
}

Then it could be easly ported into many formats. I myself want to generate golang wrapper around wp-cli, but its really redundant when it can be done automatically. Imagine having error message aswell! Can you suggest anything other than parsing output and building a tree - just what i am doing right now?

{
    "NAME": "NAME\n\n  wp\n\n",
    "DESCRIPTION": "DESCRIPTION\n\n  Manage WordPress through the command-line.\n\n",
    "SYNOPSIS": "SYNOPSIS\n\n  wp \u003ccommand\u003e\n\n",
    "SUBCOMMANDS": [
        "SUBCOMMANDS\n  cache                 Adds, removes, fetches, and flushes the WP Object Cache\n                        object",
        "  cap                   Adds, removes, and lists capabilities of a user role",
        "  cli                   Reviews current WP-CLI info, checks for updates, or\n                        views defined aliases",
        " comment               Creates, updates, deletes, and moderates comments",
        " config                Generates and reads the wp-config.php file",
        " core                  Downloads, installs, updates, and manages a WordPress\n                       installation",
        " cron                  Tests, runs, and deletes WP-Cron events; manages WP-Cron\n                       schedules",
        " db                    Performs basic database operations using credentials\n                       stored in wp-config.php",
        " embed                 Inspects oEmbed providers, clears embed cache, and more",
        " eval                  Executes arbitrary PHP code",
        " eval-file             Loads and executes a PHP file",
        " export                Exports WordPress content to a WXR file",
        " help                  Gets help on WP-CLI, or on a specific command",
        " i18n                  Provides internationalization tools for WordPress\n                       projects",
        " import                Imports content from a given WXR file",
        " language              Installs, activates, and manages language packs",
        " maintenance-mode      Activates, deactivates or checks the status of the\n                       maintenance mode of a site",
        " media                 Imports files as attachments, regenerates thumbnails, or\n                       lists registered image sizes",
        " menu                  Lists, creates, assigns, and deletes the active theme's\n                       navigation menus",
        " network               Perform network-wide operations",
        " option                Retrieves and sets site options, including plugin and\n                       WordPress settings",
        " package               Lists, installs, and removes WP-CLI packages",
        " plugin                Manages plugins, including installs, activations, and\n                       updates",
        " post                  Manages posts, content, and meta",
        " post-type             Retrieves details on the site's registered post types",
        " rewrite               Lists or flushes the site's rewrite rules, updates the\n                       permalink structure",
        " role                  Manages user roles, including creating new roles and\n                       resetting to defaults",
        " scaffold              Generates code for post types, taxonomies, plugins,\n                       child themes, etc",
        " search-replace        Searches/replaces strings in the database",
        " server                Launches PHP's built-in web server for a specific\n                       WordPress installation",
        " shell                 Opens an interactive PHP console for running and testing\n                       PHP code",
        " sidebar               Lists registered sidebars",
        " site                  Creates, deletes, empties, moderates, and lists one or\n                       more sites on a multisite installation",
        " super-admin           Lists, adds, or removes super admin users on a multisite\n                       installation",
        " taxonomy              Retrieves information about registered taxonomies",
        " term                  Manages taxonomy terms and term meta, with create,\n                       delete, and list commands",
        " theme                 Manages themes, including installs, activations, and\n                       updates",
        " transient             Adds, gets, and deletes entries in the WordPress\n                       Transient Cache",
        " user                  Manages users, along with their roles, capabilities, and\n                       meta",
        " widget                Manages widgets, including adding and moving them within\n                       sidebars",
        ""
    ],
    "OPTIONS": "",
    "GLOBAL PARAMETERS": ""
}

[schlessera]

@bukowa You could use the wp cli cmd-dump and/or wp cli param-dump, which will dump a tree structure of all known commands/params as JSON.

[bukowa]

@schlessera thanks! got a quuestion - why param-dump works only for the global parameters? It's output is much better than cmd-dump for the params. Do you think the wp cli cmd-dump could be improved to output parameters instead of synopsis just like the param-dump works for global parameters?

[bukowa]

@schlessera i ended up generating tree like that https://github.com/bukowa/gowpcli/tree/master/generated the only thing to do is to parse the params in one function https://github.com/bukowa/gowpcli/blob/master/utils.go#L11 i hope param-dump can be included in cli cmd-dump - do you think that could be possible and if / or should i open separate issue?

[schlessera]

The automatic README regeneration was successfully implemented and is being synced as an automated GHA workflow to all bundled packages.