Dynamically generate README using wp scaffold package-readme

README.md

@@ -1,59 +1,104 @@
-wp-rest-cli
-===========
+wp-cli/restful
+==============
 
-Unlock the potential of the WP REST API at the command line. Project backed by [Pressed](https://www.pressed.net/), [Chris Lema](https://chrislema.com/), [Human Made](https://hmn.md/), [Pagely](https://pagely.com/), [Pantheon](https://pantheon.io/) and many others. [Learn more →](http://wp-cli.org/restful/)
+Unlock the potential of the WP REST API at the command line.
 
 **Warning:** This project is at a very early stage. Treat it as an experiment, and understand that breaking changes will be made without warning. The sky may also fall on your head. Using wp-rest-cli requires the latest nightly build of [WP-CLI](http://wp-cli.org/), which you can install with `wp cli update --nightly`.
 
+Project backed by [Pressed](https://www.pressed.net/), [Chris Lema](https://chrislema.com/), [Human Made](https://hmn.md/), [Pagely](https://pagely.com/), [Pantheon](https://pantheon.io/) and many others. [Learn more →](http://wp-cli.org/restful/)
+
 [![Build Status](https://travis-ci.org/wp-cli/restful.svg?branch=master)](https://travis-ci.org/wp-cli/restful)
 
-Quick links: [Overview](#overview) | [Installing](#installing) | [Contributing](#Contributing)
+Quick links: [Using](#using) | [Installing](#installing) | [Contributing](#contributing)
 
-## Overview
+## Using
 
-wp-rest-cli makes [WP REST API](http://v2.wp-api.org/) endpoints available as [WP-CLI](http://wp-cli.org/) commands. It does so by:
+RESTful WP-CLI makes [WP REST API](http://v2.wp-api.org/) endpoints available as [WP-CLI](http://wp-cli.org/) commands. It does so by:
 
-* Auto-discovering WP REST API endpoints from any WordPress site running WordPress 4.4 or higher.
-* Registering WP-CLI commands for the endpoints it understands.
+1. Auto-discovering WP REST API endpoints from any WordPress site running WordPress 4.4 or higher. Target a specific WordPress install with `--path=<path>`, `--ssh=<host>`, or `--http=<domain>`.
+2. Registering WP-CLI commands for the resource endpoints it understands, in the `wp rest` namespace.
 
 For example:
 
-    $ wp rest
-    usage: wp rest attachment <command>
-       or: wp rest category <command>
-       or: wp rest comment <command>
-       or: wp rest meta <command>
-       or: wp rest page <command>
-       or: wp rest pages-revision <command>
-       or: wp rest post <command>
-       or: wp rest posts-revision <command>
-       or: wp rest status <command>
-       or: wp rest tag <command>
-       or: wp rest taxonomy <command>
-       or: wp rest type <command>
-       or: wp rest user <command>
-
-    $ wp --http=demo.wp-api.org rest tag get 65 --format=json
-    {
-      "id": 65,
-      "link": "http://demo.wp-api.org/tag/dolor-in-sunt-placeat-molestiae-ipsam/",
-      "name": "Dolor in sunt placeat molestiae ipsam",
-      "slug": "dolor-in-sunt-placeat-molestiae-ipsam",
-      "taxonomy": "post_tag"
-    }
-
-Notice how you can use `--http=<domain>` to interact with a remote WordPress site. `--http=<domain>` must be supplied as the second argument to be used. Without it, wp-rest-cli will look for endpoints of a WordPress site in a directory specified by `--path=<path>` (or the current directory, if `--path=<path` isn't supplied).
-
-There are many things wp-rest-cli can't yet do. Please [review the issue backlog](https://github.com/wp-cli/restful/issues), and open a new issue if you can't find an exising issue for your topic.
+```
+$ wp @wpdev rest
+usage: wp rest attachment <command>
+   or: wp rest category <command>
+   or: wp rest comment <command>
+   or: wp rest page <command>
+   or: wp rest page-revision <command>
+   or: wp rest post <command>
+   or: wp rest post-revision <command>
+   or: wp rest status <command>
+   or: wp rest tag <command>
+   or: wp rest taxonomy <command>
+   or: wp rest type <command>
+   or: wp rest user <command>
+
+$ wp @wpdev rest user
+usage: wp rest user create --username=<username> [--name=<name>] [--first_name=<first_name>] [--last_name=<last_name>] --email=<email> [--url=<url>] [--description=<description>] [--nickname=<nickname>] [--slug=<slug>] [--roles=<roles>] --password=<password> [--capabilities=<capabilities>] [--porcelain]
+   or: wp rest user delete <id> [--force=<force>] [--reassign=<reassign>] [--porcelain]
+   or: wp rest user diff <alias> [<resource>] [--fields=<fields>]
+   or: wp rest user edit <id>
+   or: wp rest user generate [--count=<count>] [--format=<format>] --username=<username> [--name=<name>] [--first_name=<first_name>] [--last_name=<last_name>] --email=<email> [--url=<url>] [--description=<description>] [--nickname=<nickname>] [--slug=<slug>] [--roles=<roles>] --password=<password> [--capabilities=<capabilities>] [--porcelain]
+   or: wp rest user get <id> [--context=<context>] [--fields=<fields>] [--field=<field>] [--format=<format>]
+   or: wp rest user list [--context=<context>] [--page=<page>] [--per_page=<per_page>] [--search=<search>] [--exclude=<exclude>] [--include=<include>] [--offset=<offset>] [--order=<order>] [--orderby=<orderby>] [--slug=<slug>] [--roles=<roles>] [--fields=<fields>] [--field=<field>] [--format=<format>]
+   or: wp rest user update <id> [--username=<username>] [--name=<name>] [--first_name=<first_name>] [--last_name=<last_name>] [--email=<email>] [--url=<url>] [--description=<description>] [--nickname=<nickname>] [--slug=<slug>] [--roles=<roles>] [--password=<password>] [--capabilities=<capabilities>] [--porcelain]
+```
+
+In addition to the standard list, get, create, update and delete commands, RESTful WP-CLI also registers commands for higher-level operations like:
+
+```
+# Use `wp rest * edit` to open an existing item in the editor
+$ wp rest category edit 1 --user=daniel
+---
+description:
+name: Uncategorized
+slug: uncategorized
+parent: 0
+
+# Use `wp rest * generate` to generate dummy content
+$ wp @wpdev rest post generate --count=50 --title="Test Post" --user=daniel
+Generating items  100% [==============================================] 0:01 / 0:02
+```
+
+There are many things RESTful WP-CLI can't yet do. Please [review the issue backlog](https://github.com/wp-cli/restful/issues), and open a new issue if you can't find an exising issue for your topic.
 
 ## Installing
 
-wp-rest-cli requires the latest nightly version of WP-CLI. Update with `wp cli update --nightly`.
-
-Once you've done so, you can install wp-rest-cli with `wp package install wp-cli/restful`.
+Installing this package requires WP-CLI 0.24.0-alpha-c650e14 or greater. Update to the latest nightly release with `wp cli update --nightly`.
 
-wp-rest-cli also requires the [latest WP REST API beta](https://wordpress.org/plugins/rest-api/) installed and activated on whichever WordPress you'd like to interact with. Older betas are unsupported — please keep up to date.
+Once you've done so, you can install this package with `wp package install wp-cli/restful`.
 
 ## Contributing
 
-Code and ideas are more than welcome. Please [open an issue](https://github.com/wp-cli/restful/issues) with questions, feedback, and violent dissent. Pull requests are expected to include test coverage.
+We appreciate you taking the initiative to contribute to this project.
+
+Contributing isn’t limited to just code. We encourage you to contribute in the way that best fits your abilities, by writing tutorials, giving a demo at your local meetup, helping other users with their support questions, or revising our documentation.
+
+### Reporting a bug
+
+Think you’ve found a bug? We’d love for you to help us get it fixed.
+
+Before you create a new issue, you should [search existing issues](https://github.com/wp-cli/restful/issues?q=label%3Abug%20) to see if there’s an existing resolution to it, or if it’s already been fixed in a newer version.
+
+Once you’ve done a bit of searching and discovered there isn’t an open or fixed issue for your bug, please [create a new issue](https://github.com/wp-cli/restful/issues/new) with the following:
+
+1. What you were doing (e.g. "When I run `wp post list`").
+2. What you saw (e.g. "I see a fatal about a class being undefined.").
+3. What you expected to see (e.g. "I expected to see the list of posts.")
+
+Include as much detail as you can, and clear steps to reproduce if possible.
+
+### Creating a pull request
+
+Want to contribute a new feature? Please first [open a new issue](https://github.com/wp-cli/restful/issues/new) to discuss whether the feature is a good fit for the project.
+
+Once you've decided to commit the time to seeing your pull request through, please follow our guidelines for creating a pull request to make sure it's a pleasant experience:
+
+1. Create a feature branch for each contribution.
+2. Submit your pull request early for feedback.
+3. Include functional tests with your changes. [Read the WP-CLI documentation](https://wp-cli.org/docs/pull-requests/#functional-tests) for an introduction.
+4. Follow the [WordPress Coding Standards](http://make.wordpress.org/core/handbook/coding-standards/).
+
+*This README.md is generated dynamically from the project's codebase using `wp scaffold package-readme` ([doc](https://github.com/wp-cli/scaffold-package-command#wp-scaffold-package-readme)). To suggest changes, please submit a pull request against the corresponding part of the codebase.*

bin/readme-stubs/package-description-post.md

@@ -0,0 +1,3 @@
+**Warning:** This project is at a very early stage. Treat it as an experiment, and understand that breaking changes will be made without warning. The sky may also fall on your head. Using wp-rest-cli requires the latest nightly build of [WP-CLI](http://wp-cli.org/), which you can install with `wp cli update --nightly`.
+
+Project backed by [Pressed](https://www.pressed.net/), [Chris Lema](https://chrislema.com/), [Human Made](https://hmn.md/), [Pagely](https://pagely.com/), [Pantheon](https://pantheon.io/) and many others. [Learn more →](http://wp-cli.org/restful/)

bin/readme-stubs/using.md

@@ -0,0 +1,50 @@
+RESTful WP-CLI makes [WP REST API](http://v2.wp-api.org/) endpoints available as [WP-CLI](http://wp-cli.org/) commands. It does so by:
+
+1. Auto-discovering WP REST API endpoints from any WordPress site running WordPress 4.4 or higher. Target a specific WordPress install with `--path=<path>`, `--ssh=<host>`, or `--http=<domain>`.
+2. Registering WP-CLI commands for the resource endpoints it understands, in the `wp rest` namespace.
+
+For example:
+
+```
+$ wp @wpdev rest
+usage: wp rest attachment <command>
+   or: wp rest category <command>
+   or: wp rest comment <command>
+   or: wp rest page <command>
+   or: wp rest page-revision <command>
+   or: wp rest post <command>
+   or: wp rest post-revision <command>
+   or: wp rest status <command>
+   or: wp rest tag <command>
+   or: wp rest taxonomy <command>
+   or: wp rest type <command>
+   or: wp rest user <command>
+
+$ wp @wpdev rest user
+usage: wp rest user create --username=<username> [--name=<name>] [--first_name=<first_name>] [--last_name=<last_name>] --email=<email> [--url=<url>] [--description=<description>] [--nickname=<nickname>] [--slug=<slug>] [--roles=<roles>] --password=<password> [--capabilities=<capabilities>] [--porcelain]
+   or: wp rest user delete <id> [--force=<force>] [--reassign=<reassign>] [--porcelain]
+   or: wp rest user diff <alias> [<resource>] [--fields=<fields>]
+   or: wp rest user edit <id>
+   or: wp rest user generate [--count=<count>] [--format=<format>] --username=<username> [--name=<name>] [--first_name=<first_name>] [--last_name=<last_name>] --email=<email> [--url=<url>] [--description=<description>] [--nickname=<nickname>] [--slug=<slug>] [--roles=<roles>] --password=<password> [--capabilities=<capabilities>] [--porcelain]
+   or: wp rest user get <id> [--context=<context>] [--fields=<fields>] [--field=<field>] [--format=<format>]
+   or: wp rest user list [--context=<context>] [--page=<page>] [--per_page=<per_page>] [--search=<search>] [--exclude=<exclude>] [--include=<include>] [--offset=<offset>] [--order=<order>] [--orderby=<orderby>] [--slug=<slug>] [--roles=<roles>] [--fields=<fields>] [--field=<field>] [--format=<format>]
+   or: wp rest user update <id> [--username=<username>] [--name=<name>] [--first_name=<first_name>] [--last_name=<last_name>] [--email=<email>] [--url=<url>] [--description=<description>] [--nickname=<nickname>] [--slug=<slug>] [--roles=<roles>] [--password=<password>] [--capabilities=<capabilities>] [--porcelain]
+```
+
+In addition to the standard list, get, create, update and delete commands, RESTful WP-CLI also registers commands for higher-level operations like:
+
+```
+# Use `wp rest * edit` to open an existing item in the editor
+$ wp rest category edit 1 --user=daniel
+---
+description:
+name: Uncategorized
+slug: uncategorized
+parent: 0
+
+# Use `wp rest * generate` to generate dummy content
+$ wp @wpdev rest post generate --count=50 --title="Test Post" --user=daniel
+Generating items  100% [==============================================] 0:01 / 0:02
+```
+
+There are many things RESTful WP-CLI can't yet do. Please [review the issue backlog](https://github.com/wp-cli/restful/issues), and open a new issue if you can't find an exising issue for your topic.

composer.json

@@ -1,6 +1,6 @@
 {
     "name": "wp-cli/restful",
-    "description": "Unlock the potential of the WP REST API at the command line",
+    "description": "Unlock the potential of the WP REST API at the command line.",
     "license": "MIT",
     "authors": [
         {
@@ -12,8 +12,24 @@
     "autoload": {
         "files": [ "wp-rest-cli.php" ]
     },
-    "require": {},
+    "require": {
+        "wp-cli/wp-cli": "0.24.0-alpha-c650e14"
+    },
     "require-dev": {
         "behat/behat": "~2.5"
+    },
+    "extras": {
+        "commands": [
+            "rest user list",
+            "rest user generate"
+        ],
+        "readme": {
+            "package_description": {
+                "post": "bin/readme-stubs/package-description-post.md"
+            },
+            "using": {
+                "body": "bin/readme-stubs/using.md"
+            }
+        }
     }
 }

wp-cli.yml

@@ -0,0 +1,2 @@
+require:
+  - wp-rest-cli.php