docs(CLI): upload and output flag

We are already there, except for documenting the request value type,
which definitely deserves a separate issue.

Fixes #45

src/mako/cli/docs/commands.md.mako

@@ -2,9 +2,12 @@
 <%!
     from util import (hash_comment, new_context, method_default_scope, indent_all_but_first_by, is_repeated_property)
     from cli import (subcommand_md_filename, new_method_context, SPLIT_START, SPLIT_END, pretty, SCOPE_FLAG,
-                     mangle_subcommand, is_request_value_property, FIELD_SEP, PARAM_FLAG)
+                     mangle_subcommand, is_request_value_property, FIELD_SEP, PARAM_FLAG, UPLOAD_FLAG, docopt_mode,
+                     FILE_ARG, MIME_ARG, OUT_ARG, OUTPUT_FLAG)
 
     from copy import deepcopy
+
+    escape_html = lambda n: n.replace('>', r'\>')
 %>\
 <%
     c = new_context(schemas, resources, context.get('methods'))
@@ -38,6 +41,8 @@ You can set the scope for this method like this: `${util.program_name()} --${SCO
 <%
     rprops = [p for p in mc.required_props if not is_request_value_property(mc, p)]
     oprops = [p for p in mc.optional_props if not p.get('skip_example', False)]
+
+    smd = mc.m.get('supportsMediaDownload', False)
 %>\
 % if rprops:
 # Required Scalar ${len(rprops) > 1 and 'Arguments' or 'Argument'}
@@ -76,6 +81,50 @@ can be set completely with the following arguments. Note how the cursor position
 * You can also set nested fields without setting the cursor explicitly. For example, to set the mapping from the root, you would specify `-r struct${FIELD_SEP}sub_struct${FIELD_SEP}mapping=foo=bar`. In case the cursor is not at the root, you may explicitly drill down from the root using a leading '${FIELD_SEP}' character.
 
 % endif # have request value
+% if mc.media_params:
+<%
+    protocols = [mp.protocol for mp in mc.media_params]
+%>\
+# Required Upload Flags
+
+This method supports the upload of data, using the following protocol${len(mc.media_params) > 1 and 's' or ''}:
+
+* **-${UPLOAD_FLAG} ${docopt_mode(protocols)} ${escape_html(FILE_ARG)} ${escape_html(MIME_ARG)}**
+% for mp in mc.media_params:
+    - **${mp.protocol}** - ${mp.description.split('\n')[0]}
+% endfor # each media param
+    - **${escape_html(FILE_ARG)}**
+        + Path to file to upload. It must be seekable.
+    - **${escape_html(MIME_ARG)}**
+        + the mime type, like 'application/octet-stream', which is the default
+% endif # have upload capabilities
+% if mc.response_schema or smd:
+# Optional Output Flags
+
+% if mc.response_schema:
+The method's return value a JSON encoded structure, which will be written to standard output by default.
+% endif
+% if smd:
+
+% if mc.response_schema:
+As this method supports **media download**, you may specify the `-${PARAM_FLAG} alt=media` flag to set the output to be an octet stream of the underlying media. In that case, you will not receive JSON output anymore.
+% else:
+The method's return value is a byte stream of the downloadable resource.
+% endif # handle response schema
+% endif # support media download
+
+* **-${OUTPUT_FLAG} ${escape_html(OUT_ARG)}**
+    - *${escape_html(OUT_ARG)}* specifies the *destination* to which to write the server's result to.
+% if smd and mc.response_schema:
+      It will either be a JSON-encoded structure, or the media file you are downloading.
+% elif smd:
+      It will be a byte stream of the downloadable resource.
+% else:
+      It will be a JSON-encoded structure.
+% endif
+      The *destination* may be `-` to indicate standard output, or a filepath that is to contain the received bytes.
+      If unset, it defaults to standard output.
+% endif # have output
 % if oprops:
 # Optional Method Properties
 

src/mako/cli/lib/cli.py

@@ -14,6 +14,10 @@ OUTPUT_FLAG = 'o'
 VALUE_ARG = 'v'
 SCOPE_FLAG = 'scope'
 
+FILE_ARG = '<file>'
+MIME_ARG = '<mime>'
+OUT_ARG = '<out>'
+
 FIELD_SEP = '.'
 
 CONFIG_DIR = '~/.google-service-cli'
@@ -51,6 +55,11 @@ def mangle_subcommand(name):
 def subcommand_md_filename(resource, method):
     return mangle_subcommand(resource) + '_' + mangle_subcommand(method) + '.md'
 
+def docopt_mode(protocols):
+    mode = '|'.join(protocols)
+    if len(protocols) > 1:
+        mode = '(%s)' % mode
+    return mode
 
 # split the result along split segments
 def process_template_result(r, output_file):

src/mako/cli/lib/docopt.mako

@@ -2,12 +2,9 @@
 <%!
     from util import (put_and, supports_scopes)
     from cli import (mangle_subcommand, new_method_context, PARAM_FLAG, STRUCT_FLAG, UPLOAD_FLAG, OUTPUT_FLAG, VALUE_ARG,
-                     CONFIG_DIR, SCOPE_FLAG, is_request_value_property, FIELD_SEP)
+                     CONFIG_DIR, SCOPE_FLAG, is_request_value_property, FIELD_SEP, docopt_mode, FILE_ARG, MIME_ARG, OUT_ARG)
 
     v_arg = '<%s>' % VALUE_ARG
-    file_arg = '<file>'
-    mime_arg = '<mime>'
-    out_arg = '<out>'
 %>\
 <%def name="new(c)">\
 <%
@@ -37,10 +34,8 @@ Usage:
 
     if mc.media_params:
         upload_protocols = [mp.protocol for mp in mc.media_params]
-        mode = '|'.join(upload_protocols)
-        if len(mc.media_params) > 1:
-            mode = '(%s)' % mode
-        args.append('-%s %s %s %s' % (UPLOAD_FLAG, mode, file_arg, mime_arg))
+        mode = docopt_mode(upload_protocols)
+        args.append('-%s %s %s %s' % (UPLOAD_FLAG, mode, FILE_ARG, MIME_ARG))
         upload_protocols_used = upload_protocols_used|set(upload_protocols)
     # end upload handling
 
@@ -49,8 +44,8 @@ Usage:
         param_used = True
     # end paramters
     
-    if mc.response_schema:
-        args.append('[-%s %s]' % (OUTPUT_FLAG, out_arg))
+    if mc.response_schema or mc.m.get('supportsMediaDownload', False):
+        args.append('[-%s %s]' % (OUTPUT_FLAG, OUT_ARG))
         output_used = True
     # handle output
 %>\
@@ -68,17 +63,17 @@ Options:
             'field[${FIELD_SEP}subfield]...=value' to set an actual field.
 % endif
 % if upload_protocols_used:
-    -${UPLOAD_FLAG}  <mode> ${file_arg} ${mime_arg}
+    -${UPLOAD_FLAG}  <mode> ${FILE_ARG} ${MIME_ARG}
             <mode> may be one of the following upload modes: ${put_and(sorted(upload_protocols_used))}
-            ${file_arg} path to file to upload. It must be seekable.
-            ${mime_arg} the mime type, like 'application/octet-stream', 
+            ${FILE_ARG} path to file to upload. It must be seekable.
+            ${MIME_ARG} the mime type, like 'application/octet-stream', 
             which is the default
 % endif
 % if param_used:
     -${PARAM_FLAG} ${v_arg}  set optional request parameter; ${v_arg} is of form 'name=value'
 % endif
 % if output_used:
-    -${OUTPUT_FLAG} ${out_arg}
+    -${OUTPUT_FLAG} ${OUT_ARG}
             The `destination` to which to write the server result to. 
             It will either be a json-encoded structure, or the
             media file you are downloading.