Added more documentation describing job priority and authentication

docs/explanation/authentication.rst

@@ -0,0 +1,9 @@
+Authentication and Authorization
+--------------------------------
+
+Authentication requires a client_id and a secret_key. These credentials can be
+obtained by contacting the server administrator with the queues you want priority
+access for as well as the maximum priority level to set for each queue. The
+expecation is that these credentials are shared between users on a team. 
+
+These credentials can be :doc:`set using the Testflinger CLI <../how-to/authentication>`.

docs/explanation/index.rst

@@ -8,3 +8,5 @@ This section covers conceptual questions about Testflinger.
 
     agents
     queues
+    job-priority
+    authentication

docs/explanation/job-priority.rst

@@ -0,0 +1,9 @@
+Job Priority
+============
+
+Adding job priority to your jobs gives them the ability to be selected before
+other jobs. Job priority can be specified by adding the job_priority field to
+your job YAML. This field takes an integer value with a default value of 0. Jobs
+with a higher job_priority value will be selected over jobs with lower value.
+Using this feature requires :doc:`authenticating <./authentication>` with
+Testflinger server.

docs/how-to/authentication.rst

@@ -0,0 +1,36 @@
+Authentication using Testflinger CLI
+====================================
+
+:doc:`Authentication <../explanation/authentication>` is only required for submitting jobs with priority.
+
+Authenticating with Testflinger server requires a client id and a secret key.
+These credentials can be provided to the CLI using the environment variables
+``TESTFLINGER_CLIENT_ID`` and ``TESTFLINGER_SECRET_KEY``. You can put these
+variables in a .env file:
+
+.. code-block:: shell
+
+	TESTFLINGER_CLIENT_ID=my_client_id
+	TESTFLINGER_SECRET_KEY=my_secret_key
+
+
+You can then export these variables in your shell:
+
+.. code-block:: shell
+
+	set -a
+	source .env
+	set +a
+
+
+With these variables set, you can ``testflinger_cli submit`` your jobs normally, and the authentication will be done by the CLI
+automatically.
+
+Alternatively, you can set the client id and secret key using
+command line arguments:
+
+.. code-block:: shell
+
+	$ testflinger-cli submit example-job.yaml --client_id "my_client_id" --secret_key "my_secret_key"
+
+However, this is not recommended for security purposes.

docs/how-to/index.rst

@@ -14,3 +14,5 @@ Work with jobs via Testflinger CLI
     submit-job
     cancel-job
     search-job
+    job-priority
+    authentication

docs/how-to/job-priority.rst

@@ -0,0 +1,15 @@
+Submit a test job with priority
+===============================
+
+You can add the :doc:`job_priority <../explanation/job-priority>` field to your
+job YAML like this:
+
+.. code-block:: yaml
+
+	job_priority: 100
+
+This field requires an integer value with a default value of 0. The maximum
+priority you can set depends on the permissions that you have for the queue
+you are submtting to.
+
+In order to use this field, you need to be :doc:`authenticated <./authentication>` with the server.

docs/how-to/submit-job.rst

@@ -19,12 +19,3 @@ If the job is successful submitted, you will see a ``job_id`` returned by Testfl
 
 
 You can use the ``job_id`` to further monitor and manager the submitted job.
-
-If you specify a job_priority in the YAML file, the CLI will attempt to authenticate with the server first. You can specify authentication parameters using command line options:
-
-.. code-block:: shell
-
-  $ testflinger-cli submit example-job.yaml --client_id "my_client_id" --secret_key "my_secret_key"
-
-You can also specify these as environment variables, 'TESTFLINGER_CLIENT_ID' and
-'TESTFLINGER_SECRET_KEY'.