LAVA-766 - update lava-tool manpage

Change-Id: Ib0082e5738b33be3d4f1d76bacd16ba5f3366718
Reviewed-on: https://review.linaro.org/20298
Reviewed-by: Steve McIntyre <steve.mcintyre@linaro.org>

2 files changed, 59 insertions, 95 deletions

diff --git a/man/conf.py b/man/conf.py
index 4a21378..e5e87f7 100644
--- a/man/conf.py
+++ b/man/conf.py
@@ -43,7 +43,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'LAVA Tool'
-copyright = u'2010-2015, Linaro Limited'
+copyright = u'2010-2017, Linaro Limited'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
diff --git a/man/lava-tool.rst b/man/lava-tool.rst
index 25269e3..1c1fc57 100644
--- a/man/lava-tool.rst
+++ b/man/lava-tool.rst
@@ -21,6 +21,17 @@ Subcommands
 
 Type ``lava-tool <subcommand> -h`` for help on a specific subcommand.
 
+Deprecated V1 commands
+######################
+
+The following commands are **deprecated**. Support will remain in ``lava-tool``
+for a limited time only and some calls have already been disabled for some LAVA
+instances. Once the rest of the upstream V1 support is removed at the end of
+2017, the deprecated functions within ``lava-tool`` will also be removed.
+
+data-views, deserialize, get, put, bundles, server-version, query-data-view,
+streams, make-stream, pull.
+
 Available subcommands
 #####################
 
@@ -144,6 +155,7 @@ auth-add
         --default-user        Set this user as default user for the endpoint
 
 auth-config
+    Modify authentication configuration
 
       Usage: lava-tool auth-config [-h] [--user-shortcut USER_SHORTCUT]
                              [--endpoint-shortcut ENDPOINT_SHORTCUT]
@@ -162,6 +174,17 @@ auth-config
                         Shortcut name for the endpoint.
         --default-user        Set this user as default user for the endpoint.
 
+auth-list
+    List authentication configuration
+
+      Usage: lava-tool auth-list [-h] [HOST]
+
+      Positional arguments:
+        HOST        Endpoint to list tokens for, in the form scheme://host.
+
+      Optional arguments:
+        -h, --help  show this help message and exit
+
 put
     Upload a bundle on the server **DEPRECATED**
 
@@ -250,7 +273,7 @@ resubmit-job
         -h, --help            show this help message and exit
 
 version
-    Show dashboard client version
+    Show the ``lava-tool`` client version
 
       Usage:
         lava-tool version [-h]
@@ -564,110 +587,51 @@ instance:
 
 https://staging.validation.linaro.org/static/docs/v2/
 
-The following instructions relate only to the deprecated V1 support.
+Examples
+########
 
-Contents of the JSON file
-#########################
+``lava-tool`` simplifies the token handling required to interact with one or
+more LAVA instances using XML-RPC.
 
-**DEPRECATED**
+See the lava-tool help on the instance you want to use when running tests for
+more information on using lava-tool. For example, if you have LAVA installed
+on ``http://localhost``, the lava-tool help will be available at:
+http://localhost/static/docs/v2/lava-tool.html#new-features
 
-The JSON file is submitted to the LAVA server and contains:
+Make sure you have already logged into the instance and created an
+Authentication Token using the web UI.
 
-* Demarcation as a health check or a user test.
-* The default timeout of each action within the test.
-* The logging level for the test, DEBUG or INFO.
-* The name of the test, shown in the list of jobs.
-* The location of all support files.
-* All parameters necessary to use the support files.
-* The declaration of which device(s) to use for the test.
-* The location to which the results should be uploaded.
-* The JSON determines how the test is deployed onto the device and
-  where to find the tests to be run.
+Alternatively, admins of up to date LAVA instances can generate a token for a
+user with the ``lava-server manage tokens add`` command::
 
-Basic JSON file
-###############
+ $ lava-tool auth-add
+ http://localuser@localhost/RPC2 Paste token for
+ http://localuser@localhost/RPC2/: Token added successfully for user localuser.
 
-**DEPRECATED**
-
-Your first LAVA test should use the ``DEBUG`` logging level so that it
-is easier to see what is happening.
-
-A suitable ``timeout`` for your first tests is 900 seconds.
-
-Make the ``job_name`` descriptive and explanatory, you will want to be
-able to tell which job is which when reviewing the results.
-
-Make sure the ``device_type`` matches exactly with one of the suitable
-device types listed on the server to which you want to submit this job.
-
-Change the stream to one to which you are allowed to upload results, on
-your chosen server.
-
-::
-
- {
-   "health_check": false,
-   "logging_level": "DEBUG",
-   "timeout": 900,
-   "job_name": "kvm-basic-test",
-   "device_type": "kvm",
-   "actions": [
-       {
-           "command": "deploy_linaro_image",
-           "parameters": {
-               "image": "http://images.validation.linaro.org/kvm-debian-wheezy.img.gz"
-           }
-       },
-       {
-           "command": "lava_test_shell",
-           "parameters": {
-               "testdef_repos": [
-                   {
-                       "git-repo": "git://git.linaro.org/qa/test-definitions.git",
-                       "testdef": "ubuntu/smoke-tests-basic.yaml"
-                   }
-               ],
-               "timeout": 900
-           }
-       },
-       {
-           "command": "submit_results_on_host",
-           "parameters": {
-               "stream": "/anonymous/example/",
-               "server": "http://localhost/RPC2/"
-           }
-       }
-   ]
- }
-
-Note
-####
-
-Always check your JSON syntax. A useful site for this is http://jsonlint.com.
-YAML syntax can be checked at http://yaml-online-parser.appspot.com/?yaml=
+Now set the user for this authentication as the default user for this endpoint
+(localhost)::
+
+ $ lava-tool auth-config --default-user http://localuser@localhost/RPC2
+ Auth configuration successfully updated on endpoint http://localhost/RPC2.
+
+Now set a shortcut for http://localhost/RPC2 as local::
+
+ $ lava-tool auth-config --endpoint-shortcut local http://localuser@localhost/RPC2
+ Auth configuration successfully updated on endpoint http://localhost/RPC2.
+
+ $ lava-tool auth-list
+ Endpoint URL: http://localhost/RPC2/
+ endpoint-shortcut: local
+ default-user: localuser
+ Tokens found for users: localuser
+
+.. note:: For any instance other than ``localhost``, always use ``https`` so
+   that your token is protected during transmission.
 
 Bugs and Issues
 ###############
 
-General hints and tips on :command:`lava-tool` and LAVA are
-available on the Linaro wiki: https://wiki.linaro.org/Platform/LAVA/LAVA_Tips.
-(Login is not required to read this page, only to edit.)
-
 .. note:: :command:`lava-tool` is intended for user command line interaction.
    For all scripting requirements use XMLRPC support directly. Help on using
    XMLRPC with python is in the API | Available Methods section of the LAVA instance.
    e.g. https://validation.linaro.org/api/help/ Other languages also have XMLRPC support.
-
-Testing changes to lava-tool
-############################
-
-Adding new commands to ``lava-tool`` requires changes to the :file:`entrypoints.ini` file
-and these changes need to be picked up by setuptools. The local test directory can use
-any name - just remember to remove the directory before committing your local changes
-for review.
-
-::
-
- python setup.py install --root=./_dev/lava-tool/ --install-layout=deb
- PYTHONPATH=. python ./_dev/lava-tool/usr/bin/lava-tool --help
- rm -rf ./_dev/