From d42da382873c06de4595d2c2f7b5ba0896b15547 Mon Sep 17 00:00:00 2001 From: Daniel Bachhuber Date: Tue, 19 Jul 2016 06:38:00 -0700 Subject: [PATCH] Dynamically generate README using `wp scaffold package-readme` --- README.md | 125 +++++++++++++------ bin/readme-stubs/package-description-post.md | 3 + bin/readme-stubs/using.md | 50 ++++++++ composer.json | 20 ++- wp-cli.yml | 2 + 5 files changed, 158 insertions(+), 42 deletions(-) create mode 100644 bin/readme-stubs/package-description-post.md create mode 100644 bin/readme-stubs/using.md create mode 100644 wp-cli.yml diff --git a/README.md b/README.md index 93303b8..79e7f95 100644 --- a/README.md +++ b/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=`, `--ssh=`, or `--http=`. +2. Registering WP-CLI commands for the resource endpoints it understands, in the `wp rest` namespace. For example: - $ wp rest - usage: wp rest attachment - or: wp rest category - or: wp rest comment - or: wp rest meta - or: wp rest page - or: wp rest pages-revision - or: wp rest post - or: wp rest posts-revision - or: wp rest status - or: wp rest tag - or: wp rest taxonomy - or: wp rest type - or: wp rest user - - $ 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=` to interact with a remote WordPress site. `--http=` 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=` (or the current directory, if `--path= + or: wp rest category + or: wp rest comment + or: wp rest page + or: wp rest page-revision + or: wp rest post + or: wp rest post-revision + or: wp rest status + or: wp rest tag + or: wp rest taxonomy + or: wp rest type + or: wp rest user + +$ wp @wpdev rest user +usage: wp rest user create --username= [--name=] [--first_name=] [--last_name=] --email= [--url=] [--description=] [--nickname=] [--slug=] [--roles=] --password= [--capabilities=] [--porcelain] + or: wp rest user delete [--force=] [--reassign=] [--porcelain] + or: wp rest user diff [] [--fields=] + or: wp rest user edit + or: wp rest user generate [--count=] [--format=] --username= [--name=] [--first_name=] [--last_name=] --email= [--url=] [--description=] [--nickname=] [--slug=] [--roles=] --password= [--capabilities=] [--porcelain] + or: wp rest user get [--context=] [--fields=] [--field=] [--format=] + or: wp rest user list [--context=] [--page=] [--per_page=] [--search=] [--exclude=] [--include=] [--offset=] [--order=] [--orderby=] [--slug=] [--roles=] [--fields=] [--field=] [--format=] + or: wp rest user update [--username=] [--name=] [--first_name=] [--last_name=] [--email=] [--url=] [--description=] [--nickname=] [--slug=] [--roles=] [--password=] [--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.* diff --git a/bin/readme-stubs/package-description-post.md b/bin/readme-stubs/package-description-post.md new file mode 100644 index 0000000..bbc5c79 --- /dev/null +++ b/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/) diff --git a/bin/readme-stubs/using.md b/bin/readme-stubs/using.md new file mode 100644 index 0000000..b05fd5a --- /dev/null +++ b/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=`, `--ssh=`, or `--http=`. +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 + or: wp rest category + or: wp rest comment + or: wp rest page + or: wp rest page-revision + or: wp rest post + or: wp rest post-revision + or: wp rest status + or: wp rest tag + or: wp rest taxonomy + or: wp rest type + or: wp rest user + +$ wp @wpdev rest user +usage: wp rest user create --username= [--name=] [--first_name=] [--last_name=] --email= [--url=] [--description=] [--nickname=] [--slug=] [--roles=] --password= [--capabilities=] [--porcelain] + or: wp rest user delete [--force=] [--reassign=] [--porcelain] + or: wp rest user diff [] [--fields=] + or: wp rest user edit + or: wp rest user generate [--count=] [--format=] --username= [--name=] [--first_name=] [--last_name=] --email= [--url=] [--description=] [--nickname=] [--slug=] [--roles=] --password= [--capabilities=] [--porcelain] + or: wp rest user get [--context=] [--fields=] [--field=] [--format=] + or: wp rest user list [--context=] [--page=] [--per_page=] [--search=] [--exclude=] [--include=] [--offset=] [--order=] [--orderby=] [--slug=] [--roles=] [--fields=] [--field=] [--format=] + or: wp rest user update [--username=] [--name=] [--first_name=] [--last_name=] [--email=] [--url=] [--description=] [--nickname=] [--slug=] [--roles=] [--password=] [--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. diff --git a/composer.json b/composer.json index aaca25f..0b3eb4e 100644 --- a/composer.json +++ b/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" + } + } } } diff --git a/wp-cli.yml b/wp-cli.yml new file mode 100644 index 0000000..f551138 --- /dev/null +++ b/wp-cli.yml @@ -0,0 +1,2 @@ +require: + - wp-rest-cli.php