Add documentation for the description kwarg for data types and comman…

…ds (#72)

* Add documentation for the description kwarg for data types and commands

* Revert import in examples/

docs/source/index.md

@@ -46,15 +46,15 @@ def setup(opts):
     else:
         return little_model()
 
-inputs = { 'noise_vector': vector(length=128) }
+inputs = { 'noise_vector': vector(length=128, description='A random seed.') }
 outputs = { 'image': image(width=512, height=512) }
 
 # The @runway.command() decorator is used to create interfaces to call functions
 # remotely via an HTTP endpoint. This lets you send data to, or get data from,
 # your model. Each command creates an HTTP route that the Runway app will use
 # to communicate with your model (e.g. POST /generate). Multiple commands
 # can be defined for the same model.
-@runway.command('generate', inputs=inputs, outputs=outputs)
+@runway.command('generate', inputs=inputs, outputs=outputs, description='Generate an image.')
 def generate(model, input_args):
     # Functions wrapped by @runway.command() receive two arguments:
     # 1. Whatever is returned by a function wrapped by @runway.setup(),

examples/docs_code_snippets/runway_module_command.py

@@ -7,20 +7,29 @@ def setup():
     return model()
 
 sample_inputs= {
-    "z": vector(length=512),
+    "z": vector(length=512, description="The seed used to generate an output image."),
     "category": category(choices=["day", "night"])
 }
 
 sample_outputs = {
     "image": image(width=1024, height=1024)
 }
 
-@runway.command("sample", inputs=sample_inputs, outputs=sample_outputs)
+# Descriptions are used to document each data type and `@runway.command()`; Their values appear
+# in the app as tooltips. Writing detailed descriptions for each model option goes a long way
+# towards helping users learn how to interact with your model. Write descriptions as full
+# sentences.
+sample_description = "Generate a new image based on a z-vector and an output style: Day or night."
+@runway.command("sample",
+                inputs=sample_inputs,
+                outputs=sample_outputs,
+                description=sample_description)
 def sample(model, inputs):
     # The parameters passed to a function decorated by @runway.command() are:
-    #   1. The return value of a function wrapped by @runway.setup(), usually a model
+    #   1. The return value of a function wrapped by @runway.setup(), usually a model.
     #   2. The inputs sent with the HTTP request to the /<command_name> endpoint,
     #      as defined by the inputs keyword argument delivered to @runway.command().
     img = model.sample(z=inputs["z"], category=inputs["category"])
+    # `img` can be a PIL or numpy image. It will be encoded as a base64 URI string
+    # automatically by @runway.command().
     return { "image": img }
-

examples/docs_code_snippets/runway_module_setup.py

@@ -2,8 +2,15 @@
 from runway.data_types import category
 from your_code import model
 
-options = {"network_size": category(choices=[64, 128, 256, 512], default=256)}
+# Descriptions are used to document each data type; Their values appear in the app as
+# tooltips. Writing detailed descriptions for each model option goes a long way towards
+# helping users learn how to interact with your model. Write descriptions as full sentences.
+network_size_description = "The size of the network. A larger number will result in" \
+                           "better accuracy at the expense of increased latency."
+options = {
+  "network_size": category(choices=[64, 128, 256, 512], default=256, description=network_size_description)
+}
 @runway.setup(options=options)
 def setup(opts):
     print("Setup ran, and the network size is {}".format(opts["network_size"]))
-    return model(network_size=opts["network_size"])
+    return model(network_size=opts["network_size"])

runway/model.py

@@ -185,7 +185,11 @@ def setup(self, decorated_fn=None, options=None):
             from runway.data_types import category
             from your_code import model
 
-            options = {"network_size": category(choices=[64, 128, 256, 512], default=256)}
+            # Descriptions are used to document each data type; Their values appear in the app as
+            # tooltips. Writing detailed descriptions for each model option goes a long way towards
+            # helping users learn how to interact with your model. Write descriptions as full sentences.
+            network_size_description = "The size of the network. A larger number will result in better accuracy at the expense of increased latency."
+            options = { "network_size": category(choices=[64, 128, 256, 512], default=256, description=network_size_description) }
             @runway.setup(options=options)
             def setup(opts):
                 print("Setup ran, and the network size is {}".format(opts["network_size"]))
@@ -241,15 +245,23 @@ def setup():
                 return model()
 
             sample_inputs= {
-                "z": vector(length=512),
+                "z": vector(length=512, description="The seed used to generate an output image."),
                 "category": category(choices=["day", "night"])
             }
 
             sample_outputs = {
                 "image": image(width=1024, height=1024)
             }
 
-            @runway.command("sample", inputs=sample_inputs, outputs=sample_outputs)
+            # Descriptions are used to document each data type and `@runway.command()`; Their values appear
+            # in the app as tooltips. Writing detailed descriptions for each model option goes a long way
+            # towards helping users learn how to interact with your model. Write descriptions as full
+            # sentences.
+            sample_description = "Generate a new image based on a z-vector and an output style: Day or night."
+            @runway.command("sample",
+                            inputs=sample_inputs,
+                            outputs=sample_outputs,
+                            description=sample_description)
             def sample(model, inputs):
                 # The parameters passed to a function decorated by @runway.command() are:
                 #   1. The return value of a function wrapped by @runway.setup(), usually a model.
@@ -260,6 +272,13 @@ def sample(model, inputs):
                 # automatically by @runway.command().
                 return { "image": img }
 
+        .. note::
+            All ``@runway.command()`` decorators accept a ``description`` keyword argument
+            that can be used to describe what the command does. Descriptions appear as
+            tooltips in the app and help users learn what the command does. It's best
+            practice to write full-sentence descriptions for each of your input variables
+            and commands.
+
         :param name: The name of the command. This name is used to create the
             HTTP route associated with the command
             (i.e. a name of "generate_text" will generate a ``/generate_text``
@@ -277,7 +296,7 @@ def sample(model, inputs):
         :param description: A text description of what this command does.
             If this parameter is present its value will be rendered as a tooltip
             in Runway. Defaults to None.
-        :type description: string
+        :type description: string, optional
         :raises Exception: An exception if there isn't at least one key value
             pair for both inputs and outputs dictionaries
         :return: A decorated function