From c45d6e51c29bcf2e16165db92f6cd027102536f5 Mon Sep 17 00:00:00 2001
From: Chris White <chris@prefect.io>
Date: Tue, 25 Sep 2018 17:09:45 -0700
Subject: [PATCH] Touched up some call signature issues and embedded HTML right
 into the doc for task.run()

---
 docs/generate_docs.py    | 17 +++++++++++++----
 src/prefect/core/task.py | 31 +++++++++++++++----------------
 2 files changed, 28 insertions(+), 20 deletions(-)

diff --git a/docs/generate_docs.py b/docs/generate_docs.py
index 662c3b760d88..fc4f59e01476 100644
--- a/docs/generate_docs.py
+++ b/docs/generate_docs.py
@@ -175,9 +175,14 @@
     {
         "page": "tasks/function.md",
         "classes": [prefect.tasks.core.function.FunctionTask],
+        "title": "FunctionTask",
     },
-    {"page": "tasks/shell.md", "classes": [prefect.tasks.shell.ShellTask]},
-    {"page": "utilities/bokeh.md", "classes": [BokehRunner]},
+    {
+        "page": "tasks/shell.md",
+        "classes": [prefect.tasks.shell.ShellTask],
+        "title": "ShellTask",
+    },
+    {"page": "utilities/bokeh.md", "classes": [BokehRunner], "title": "BokehRunner"},
     {
         "page": "utilities/collections.md",
         "classes": [prefect.utilities.collections.DotDict],
@@ -308,7 +313,7 @@ def get_call_signature(obj):
         kwargs = list(zip(args[-len(defaults) :], defaults))  # true kwargs
 
     varargs = [f"*{varargs}"] if varargs else []
-    varkwargs = [f"*{varkwargs}"] if varkwargs else []
+    varkwargs = [f"**{varkwargs}"] if varkwargs else []
 
     return standalone, varargs, kwargs, varkwargs
 
@@ -318,8 +323,12 @@ def format_signature(obj):
     standalone, varargs, kwargs, varkwargs = get_call_signature(obj)
     # NOTE: I assume the call signature is f(x, y, ..., *args, z=1, ...,
     # **kwargs) and NOT f(*args, x, y, ...)
+    add_quotes = lambda s: f'"{s}"' if isinstance(s, str) else s
     psig = ", ".join(
-        standalone + varargs + [f"{name}={val}" for name, val in kwargs] + varkwargs
+        standalone
+        + varargs
+        + [f"{name}={add_quotes(val)}" for name, val in kwargs]
+        + varkwargs
     )
     return psig
 
diff --git a/src/prefect/core/task.py b/src/prefect/core/task.py
index 289671a5527a..8aed26b518ef 100644
--- a/src/prefect/core/task.py
+++ b/src/prefect/core/task.py
@@ -175,22 +175,21 @@ def run(self) -> None:  # type: ignore
         """
         The `run()` method is called (with arguments, if appropriate) to run a task.
 
-        In addition to running arbitrary functions, tasks can interact with
-        Prefect in a few ways:
-            1. Return an optional result. When this function runs successfully,
-                the task is considered successful and the result (if any) can be
-                made available to downstream tasks.
-            2. Raise an error. Errors are interpreted as failure.
-            3. Raise a signal. Signals can include `FAIL`, `SUCCESS`, `RETRY`, `SKIP`, etc.
-                and indicate that the task should be put in the indicated
-                state.
-                - `FAIL` will lead to retries if appropriate
-                - `SUCCESS` will cause the task to be marked successful
-                - `RETRY` will cause the task to be marked for retry, even if `max_retries`
-                    has been exceeded
-                - `SKIP` will skip the task and possibly propogate the skip state through the
-                    flow, depending on whether downstream tasks have
-                    `skip_on_upstream_skip=True`.
+        In addition to running arbitrary functions, tasks can interact with Prefect in a few ways:
+        <ul><li> Return an optional result. When this function runs successfully,
+            the task is considered successful and the result (if any) can be
+            made available to downstream tasks. </li>
+        <li> Raise an error. Errors are interpreted as failure. </li>
+        <li> Raise a [signal](../engine/signals.html). Signals can include `FAIL`, `SUCCESS`, `RETRY`, `SKIP`, etc.
+            and indicate that the task should be put in the indicated state.
+                <ul>
+                <li> `FAIL` will lead to retries if appropriate </li>
+                <li> `SUCCESS` will cause the task to be marked successful </li>
+                <li> `RETRY` will cause the task to be marked for retry, even if `max_retries`
+                    has been exceeded </li>
+                <li> `SKIP` will skip the task and possibly propogate the skip state through the
+                    flow, depending on whether downstream tasks have `skip_on_upstream_skip=True`. </li></ul>
+        </li></ul>
         """
         pass