doc: Update docs.

  * Add send resource and schema doc.
  * Update other docs.

Change-Id: I98fd1c3fc293c781e3fab2636af3ad0c5567e9a0

6 files changed, 149 insertions, 1 deletions

diff --git a/doc/collection-job.rst b/doc/collection-job.rst
index 72ca620..4a46b7d 100644
--- a/doc/collection-job.rst
+++ b/doc/collection-job.rst
@@ -166,6 +166,10 @@ POST
  :status 415: Wrong content type.
  :status 422: No real JSON data provided.
 
+ .. warning::
+
+    Triggering email report through the job resources will be depracated.
+
  **Example Requests**
 
  .. sourcecode:: http 
diff --git a/doc/collection-send.rst b/doc/collection-send.rst
new file mode 100644
index 0000000..6a456c7
--- /dev/null
+++ b/doc/collection-send.rst
@@ -0,0 +1,82 @@
+.. _collection_send:
+
+send
+----
+
+Trigger email reports for boot and build tests.
+
+More info about the send schema can be found :ref:`here <schema_send>`.
+
+GET
+***
+
+.. caution::
+    Not implemented. Will return a :ref:`status code <http_status_code>`
+    of ``501``.
+
+.. note::
+
+    For information about the triggered email reports, see :ref:`the report resource <collection_report>`
+
+POST
+****
+
+.. http:post:: /send
+
+ Schedule boot and/or build email report.
+
+ For more info on all the required JSON request fields, see the :ref:`schema for POST requests <schema_send_post>`.
+
+ :reqjson string job: The name of the job.
+ :reqjson string kernel: The name of the kernel.
+ :reqjson boolean boot_report: If the boot report should be created and sent. Default to 0 (false).
+ :reqjson boolean build_report: If the build report should be created and sent. Default to 0 (false).
+ :reqjson send_to: A string or an array of strings of email addresses where to send the reports.
+ :reqjson boot_send_to: A string or an array of strings of email addresses where to send only the boot report.
+ :reqjson build_send_to: A string or an array of strings of email addresses where to send only the build report.
+ :reqjson int delay: Number of seconds after which the email report will be sent. Default to 60*60 seconds.
+
+ :reqheader Authorization: The token necessary to authorize the request.
+ :reqheader Content-Type: Content type of the transmitted data, must be ``application/json``.
+ :reqheader Accept-Encoding: Accept the ``gzip`` coding.
+
+ :resheader Content-Type: Will be ``application/json; charset=UTF-8``.
+
+ :status 202: The request has been accepted and will be processed.
+ :status 400: JSON data not valid.
+ :status 403: Not authorized to perform the operation.
+ :status 415: Wrong content type.
+ :status 422: No real JSON data provided.
+
+ **Example Requests**
+
+ .. sourcecode:: http 
+
+    POST /send HTTP/1.1
+    Host: api.kernelci.org
+    Content-Type: application/json
+    Accept: */*
+    Authorization: token
+
+    {
+        "job": "next",
+        "kernel": "next-20140801",
+        "boot_report": 1,
+        "send_to": ["email@example.net"],
+        "delay": 14400
+    }
+
+DELETE
+******
+
+.. caution::
+    Not implemented. Will return a :ref:`status code <http_status_code>`
+    of ``501``.
+
+More Info
+*********
+
+* :ref:`Send schema <schema_send>`
+* :ref:`Send report <schema_report>`
+* :ref:`API results <intro_schema_results>`
+* :ref:`Schema time and date <intro_schema_time_date>`
diff --git a/doc/collections.rst b/doc/collections.rst
index eba8670..ccf1aa9 100644
--- a/doc/collections.rst
+++ b/doc/collections.rst
@@ -18,3 +18,4 @@ Resources
     collection-lab
     collection-version
     collection-report
+    collection-send
diff --git a/doc/schema-job.rst b/doc/schema-job.rst
index 878fa21..64135f9 100644
--- a/doc/schema-job.rst
+++ b/doc/schema-job.rst
@@ -85,7 +85,7 @@ GET
 POST
 ****
 
-The following schema covers the data that should be available in the job JSON
+The following schema covers the data that should be available in the JSON
 data sent to the server.
 
 ::
diff --git a/doc/schema-send.rst b/doc/schema-send.rst
new file mode 100644
index 0000000..9f0a009
--- /dev/null
+++ b/doc/schema-send.rst
@@ -0,0 +1,60 @@
+.. _schema_send:
+
+send
+----
+
+.. _schema_send_post:
+
+POST
+****
+
+The following schema covers the data that should be available in the JSON
+data sent to the server.
+
+::
+
+    {
+        "title": "send",
+        "description": "Data to trigger the email report",
+        "type": "object",
+        "properties": {
+            "job": {
+                "type": "string",
+                "description": "The job name associated with the object"
+            },
+            "kernel": {
+                "type": "string",
+                "description": "The kernel name associated with the object"
+            },
+            "boot_report": {
+                "type": "boolean",
+                "description": "Whether the boot report should be created and sent",
+                "default": 0
+            },
+            "build_report": {
+                "type": "boolean",
+                "description": "Whether the build report should be created and sent",
+                "default": 0
+            },
+            "boot_send_to": {
+                "type": ["string", "array"],
+                "description": "The emails to sent the boot report to"
+            },
+            "build_send_to": {
+                "type": ["string", "array"],
+                "description": "The emails to send the build report to"
+            },
+            "send_to": {
+                "type": ["string", "array"],
+                "description": "The emails to send the reports to, will be appended to the more specific email control values"
+            }
+        },
+        "required": ["job", "kernel"]
+    }
+
+More Info
+*********
+
+* :ref:`Report schema <schema_report>`
+* :ref:`API results <intro_schema_results>`
+* :ref:`Schema time and date <intro_schema_time_date>`
diff --git a/doc/schema.rst b/doc/schema.rst
index 5203dc8..2761c39 100644
--- a/doc/schema.rst
+++ b/doc/schema.rst
@@ -13,3 +13,4 @@ Schema
     schema-batch
     schema-lab
     schema-report
+    schema-send