Repository: PrefectHQ/prefect

Issue:
Update doc list indentation
Currently _all_ lists in our docs have a particular padding / styling which has heavy indentation; this works well for API argument documentation, but not so much for generic markdown lists (see, e.g., the lists in https://docs.prefect.io/tutorials/airflow_migration.html#overview)

We should be more nuanced in our application of this style.
Doc images are not sized appropriately
For example:

https://docs.prefect.io/tutorials/triggers-and-references.html

The image takes over the text.

**cc**: @itsngansense 


Discussion:

In addition, some images appear to have broken links? https://docs.prefect.io/tutorials/task-retries.html  Not sure when / how that happened

Resolving patch:
diff --git a/docs/generate_docs.py b/docs/generate_docs.py
--- a/docs/generate_docs.py
+++ b/docs/generate_docs.py
@@ -99,8 +99,8 @@ def format_lists(doc):
     lists = re.findall(
         r"(Args\:|Returns\:|Raises\:)(.*?)\s+(-.*?)(\n\n|$)", doc, re.DOTALL
     )  # find formatted lists
-    ul_tag = "<ul>"
-    li_tag = "<li>"
+    ul_tag = '<ul class="args">'
+    li_tag = '<li class="args">'
     for section, _, items, ending in lists:
         if section.startswith(("Returns:", "Raises:")) and ":" not in items:
             doc = doc.replace(
diff --git a/src/prefect/utilities/logging.py b/src/prefect/utilities/logging.py
--- a/src/prefect/utilities/logging.py
+++ b/src/prefect/utilities/logging.py
@@ -51,7 +51,7 @@ def configure_logging(testing=False) -> logging.Logger:
             by configuring a "prefect-test-logger" instead of the standard "prefect" logger
 
     Returns:
-        - logging.Logger
+        - logging.Logger: a configured logging object
     """
     name = "prefect-test-logger" if testing else "prefect"
     logger = logging.getLogger(name)
@@ -84,7 +84,7 @@ def get_logger(name: str = None) -> logging.Logger:
             the root logger's settings.
 
     Returns:
-        - logging.Logger
+        - logging.Logger: a configured logging object with the appropriate name
     """
     if name is None:
         return prefect_logger


Test patch:
diff --git a/docs/test_generate_docs.py b/docs/test_generate_docs.py
--- a/docs/test_generate_docs.py
+++ b/docs/test_generate_docs.py
@@ -178,15 +178,15 @@ def test_format_list_on_normal_doc():
     formatted_doc = format_lists(doc)
     assert formatted_doc == (
         "\n    Does a thing.\n\n    Args:\n        "
-        "<ul>"
-        "<li>"
+        '<ul class="args">'
+        '<li class="args">'
         "`x (bool)`: it's x\n        </li>"
-        "<li>"
+        '<li class="args">'
         "`y (bool)`: it's y</li></ul>    "
-        "Returns:\n        <ul>"
-        "<li>whatever you want</li></ul>"
-        "\n\n    Raises:\n        <ul>"
-        "<li>`NotImplementedError`: because it doesnt exist\n    </li></ul>"
+        'Returns:\n        <ul class="args">'
+        '<li class="args">whatever you want</li></ul>'
+        '\n\n    Raises:\n        <ul class="args">'
+        '<li class="args">`NotImplementedError`: because it doesnt exist\n    </li></ul>'
     )
 
 
@@ -203,8 +203,8 @@ def my_fun():
     formatted = format_doc(my_fun)
     assert formatted == (
         "Indicates that a task should not run and wait for manual execution.\n\n"
-        "**Args**:     <ul>"
-        "<li>"
+        '**Args**:     <ul class="args">'
+        '<li class="args">'
         "`message (Any, optional)`: Defaults to `None`. A message about the signal.</li></ul>"
     )