Add documentation on rbt close --json.
This adds a section to the `rbt close` docs that covers the new `--json`
parameter. This documents the success and error schema, and shows off
usage for both.
Testing Done:
Built the docs. Checked for any obvious errors or spelling errors.
Reviewed at
@@ -11,4 +11,86 @@ option.
.. rbt-command-usage::
+
+
+.. _rbt-close-json:
+
+JSON Output
+===========
+
+.. versionadded:: 3.0
+
+When running with :option:`--json`, the result of the close operation will be
+outputted as JSON. This can be used by programs that wrap RBTools in order to
+automate closing review requests.
+
+
+Successful Payloads
+-------------------
+
+When closing is successful, the results are in the form of:
+
+.. code-block:: javascript
+
+ {
+ "status": "success",
+
+ // The resulting close type ("submitted" or "discarded").
+ "close_type": "<string>",
+
+ // The provided close description.
+ "description": "<string>",
+
+ // The ID of the review request.
+ "review_request_id": <int>,
+
+ // The URL of the review request.
+ "review_request_url": "<string>"
+ }
+
+For example:
+
+.. code-block:: console
+
+ $ rbt close --json --description "Committed to release-6.x" 123
+ {
+ "close_type": "submitted",
+ "description": "Committed to release-6.x",
+ "review_request_id": 123,
+ "review_request_url": "https://example.com/r/123/"
+ }
+
+
+Error Payloads
+--------------
+
+When there's an error closing a review request (for instance, if it's already
+closed), the results will be in the form of:
+
+.. code-block:: javascript
+
+ {
+ "status": "failed",
+
+ // A list of errors from the operation.
+ "errors": [
+ "<string>",
+ ...
+ ]
+ }
+
+For example:
+
+.. code-block:: console
+
+ $ rbt close --json 123
+
+ {
+ "errors": [
+ "Review request #123 is already submitted."
+ ],
+ "status": "failed"
+ }
+
+
.. rbt-command-options::
