Improve documentation of tasks w.r.t required/option/defauled fields. (…

…#3447)

Right now it is typical to have an option description that looks like
this:

```
	--path PATH
	Required

	The path to the metadata source to be deployed

	Default: unpackaged/config/qa
```

This is paradoxical. Either the option is required, or
it is defaulted. It can't be both.

The new format looks like this:

```
    --path PATH

      The path to the metadata source to be deployed

      Default: unpackaged/config/qa

    --unmanaged UNMANAGED

        If True, changes namespace_inject to replace tokens with a blank
        string

      Optional
```

"Optional" or "Required" is only printed if there is no default.

cumulusci/tests/test_utils.py

@@ -236,16 +236,16 @@ def test_doc_task(self, task_config):
 ``$ cci task run scoop_icecream``\n\n
 Options\n------------------------------------------\n\n
 ``--flavor VANILLA``
-\t *Required*\n
-\t What flavor\n
+
+\t What flavor
+\n *Required*\n
 \t Type: string\n
-``--color COLOR``
-\t *Optional*\n
+``--color COLOR``\n
 \t What color\n
 \t Default: black\n
 ``--size SIZE``
-\t *Optional*\n
-\t How big"""
+\n\t How big
+\n *Optional*"""
         )
 
     def test_get_command_syntax(self, task_config):
@@ -285,15 +285,13 @@ def test_get_option_usage_string(self, option_info):
     def test_create_task_options_doc(self, option_info):
         option_one_doc = utils.create_task_options_doc(option_info[:1])
         option_two_doc = utils.create_task_options_doc(option_info[1:])
-
         assert option_one_doc == [
-            "\t *Required*",
             "\n\t description",
             "\n\t Default: default",
             "\n\t Type: option_type",
         ]
 
-        assert option_two_doc == ["\t *Optional*", "\n\t Brief description here."]
+        assert option_two_doc == ["\n\t Brief description here.", "\n *Optional*"]
 
     def test_document_flow(self):
         project_config = create_project_config("TestOwner", "TestRepo")

cumulusci/utils/__init__.py

@@ -440,18 +440,17 @@ def create_task_options_doc(task_options):
         if usage_str:
             doc.append(f"\n``{usage_str}``")
 
-        if option.get("required"):
-            doc.append("\t *Required*")
-        else:
-            doc.append("\t *Optional*")
-
         description = option.get("description")
         if description:
             doc.append(f"\n\t {description}")
 
         default = option.get("default")
         if default:
             doc.append(f"\n\t Default: {default}")
+        elif option.get("required"):
+            doc.append("\n *Required*")
+        else:
+            doc.append("\n *Optional*")
 
         option_type = option.get("option_type")
         if option_type: