Update docs and CLI options to match

Updates the documentation of the CLI to match the options supported
Also adds some type checking to the CLI for input UUID, and sets some
default values for OS auth variables that can be reasonably defaulted
Sets up the options on input to the output format to use 'cli' as the
default instead of 'format', providing for a path to make more cli
friendly outputs for actions (instead of raw json/yaml as appropriate).
Fixes some markdown in html problems.

Change-Id: Ie0eaa34ad1106b5a963b69ffc7eb727c13ede244

docs/CLI.md

@@ -4,18 +4,23 @@ All commands will utilize the following environment variables to determine
 necessary information for execution, unless otherwise noted.
 
 <dl>
-  <dt>Openstack Keystone Authorization Environment variables</dt>
+  <dt>Openstack Keystone Authorization environment variables</dt>
   <dd>
     The Shipyard CLI/API Client will check for the presence of appropriate
     environment setup to do authentication on behalf of the user.
     The openrc variables that will be used are as follows:<br />
-    OS_PROJECT_DOMAIN_NAME<br />
-    OS_USER_DOMAIN_NAME<br />
+    OS_PROJECT_DOMAIN_NAME ("default" if not specified)<br />
+    OS_USER_DOMAIN_NAME ("default" if not specified)<br />
     OS_PROJECT_NAME<br />
     OS_USERNAME<br />
     OS_PASSWORD<br />
-    OS_AUTH_URL<br />
-    OS_IDENTITY_API_VERSION<br />
+    OS_AUTH_URL - The fully qualified identity endpoint.
+    E.g. http://keystone.ucp.fully.qualified.name:80/v3<br />
+  </dd>
+  <dt>Openstack Keystone Authorization environment variables not used</dt>
+  <dd>
+    OS_IDENTITY_API_VERSION -- this value will be ignored as Shipyard only
+    supports version 3 at this time<br />
   </dd>
 </dl>
 
@@ -28,8 +33,9 @@ shipyard <--these options> subcommands...
 
 shipyard
   [--context-marker=<uuid>]
-  [--os_{various}=<value>]
   [--debug/--no-debug]
+  [--os_{various}=<value>]
+  [--output-format=[format | raw | cli]]  (default = cli)
   <subcommands, as noted in this document>
 ```
 <dl>
@@ -40,22 +46,35 @@ shipyard
     interaction. If not specified, Shipyard will supply a new UUID to serve
     as this marker. (optional)
   </dd>
+  <dt>--debug | --no-debug (default)</dt>
+  <dd>
+    Enable/disable debugging of this CLI and API client.
+  </dd>
   <dt>--os_{various}=&lt;value&gt;</dt>
   <dd>
     See supported Openstack Keystone Authorization Environment variables above
     for the list of supported names, converting to a downcase version of the
     environment variable.<br />
-    E.g.: --os_auth_url=http://...:80/v3
-    While these options are optional, if not specified, the environment
-    variables will be used instead. The Keystone os_auth_url should reference
-    the exposed keystone:port for the target Shipyard environment, as this
-    Keystone will be used to discover the instance of Shipyard.
+    E.g.: --os_auth_url=http://keystone.ucp:80/v3<br />
+    If not specified, the environment variables matching these actions will be
+    used instead. The Keystone os_auth_url should reference the exposed
+    keystone:port for the target Shipyard environment, as this Keystone will
+    be used to discover the instance of Shipyard. For most invocations other
+    than help, a valid combination of values must be resolved to authenticate
+    and authorize the user's invocation.
+  </dd>
+  <dt>--output-format=[format | raw | cli]  (default = cli)</dt>
+  <dd>
+    Specifies the desired output formating such that:<br />
+    <b>format</b>: Display the raw ouptut from the invoked Shipyard API in a
+    column restricted mode.<br />
+    <b>raw</b>: Display the result from the invoked Shipyard API as-is, without
+    modification.<br />
+    <b>cli</b>: (default) Display results in a plain text interpretation of the
+    response from the invoked Shipyard API.
   </dd>
 </dl>
 
-## Context Marker
-
-
 # Commit Commands
 ## commit configdocs
 Attempts to commit the Shipyard Buffer documents, first invoking validation
@@ -147,7 +166,6 @@ Example:
   <dt>&lt;action command&gt;</dt>
   <dd>
     The action to invoke.
-    See [Action Commands](API_action_commands.md) for supported actions
   </dd>
   <dt>--param=&lt;parameter&gt;</dt>
   <dd>

shipyard_client/cli/commands.py

@@ -35,20 +35,24 @@ from shipyard_client.cli.input_checks import check_control_action, check_id
     ' logs, transactions, etc. in downstream activities triggered by this'
     ' interaction. If not specified, Shipyard will supply a new UUID to serve'
     ' as this marker. (optional)',
-    required=False)
+    required=False,
+    type=click.UUID)
 @click.option('--debug/--no-debug', default=False, help='Turn Debug on.')
 @click.option(
     '--output-format',
     'output_format',
     required=False,
-    type=click.Choice(['format', 'raw']))
+    type=click.Choice(['format', 'raw', 'cli']),
+    default='cli')
 # Supported Environment Variables
-@click.option(
-    '--os_project_domain_name',
-    envvar='OS_PROJECT_DOMAIN_NAME',
-    required=False)
-@click.option(
-    '--os_user_domain_name', envvar='OS_USER_DOMAIN_NAME', required=False)
+@click.option('--os_project_domain_name',
+              envvar='OS_PROJECT_DOMAIN_NAME',
+              required=False,
+              default='default')
+@click.option('--os_user_domain_name',
+              envvar='OS_USER_DOMAIN_NAME',
+              required=False,
+              default='default')
 @click.option('--os_project_name', envvar='OS_PROJECT_NAME', required=False)
 @click.option('--os_username', envvar='OS_USERNAME', required=False)
 @click.option('--os_password', envvar='OS_PASSWORD', required=False)
@@ -94,7 +98,7 @@ def shipyard(ctx, context_marker, debug, os_project_domain_name,
 
     ctx.obj['API_PARAMETERS'] = {
         'auth_vars': auth_vars,
-        'context_marker': context_marker,
+        'context_marker': str(context_marker) if context_marker else None,
         'debug': debug
     }
 

shipyard_client/cli/help/output.py

@@ -32,24 +32,16 @@ For information of the following topics, run shipyard help <topic>
 
 def actions():
     return '''ACTIONS
-
-
-Supported Actions
-No supported actions at this time.
-
-
-Actions Under Development
+The workflow actions that may be invoked using Shipyard
 
 deploy_site: Triggers the initial deployment of a site using the latest
              committed configuration documents.
 
 update_site: Triggers the initial deployment of a site, using the latest
              committed configuration documents.
-             Steps:
-                 (same as deploy_site)
 
 redeploy_server: Using parameters to indicate which server(s), triggers a
-                 redeployment of server to the last known good design and
+                 redeployment of servers to the last committed design and
                  secrets.
     '''
 

shipyard_client/tests/unit/cli/test_shipyard_commands.py

@@ -21,7 +21,7 @@ from shipyard_client.api_client.shipyardclient_context import \
 
 
 def test_shipyard():
-    context_marker = '--context-marker=UUID'
+    context_marker = '--context-marker=88888888-4444-4444-4444-121212121212'
     debug = '--debug'
     os_project_domain_name = (
         '--os_project_domain_name=OS_PROJECT_DOMAIN_NAME_test')
@@ -47,4 +47,8 @@ def test_shipyard():
             os_project_name, os_username, os_password, os_auth_url, debug,
             'commit', 'configdocs'
         ])
-    mock_method.assert_called_once_with(auth_vars, 'UUID', True)
+    mock_method.assert_called_once_with(
+        auth_vars,
+        '88888888-4444-4444-4444-121212121212',
+        True
+    )