Show descriptions of templates in ddev create help (#18039)

* Show descriptions of templates in ddev create help

* add changelog

* add more template descriptions

* Apply suggestions from code review

Co-authored-by: Bryce Eadie <[email protected]>

* Update datadog_checks_dev/datadog_checks/dev/tooling/templates/integration/tile/README.md

Co-authored-by: Bryce Eadie <[email protected]>

---------

Co-authored-by: Bryce Eadie <[email protected]>

datadog_checks_dev/changelog.d/18039.added

@@ -0,0 +1 @@
+Show descriptions of templates in ddev create help.

datadog_checks_dev/datadog_checks/dev/tooling/commands/create.py

@@ -107,16 +107,43 @@ def display_path_tree(path_tree):
       }
     ]"""
 
+VALID_TEMPLATES = get_valid_templates()
+
+
+def _valid_template_description():
+    title = 'Types of Integrations'
+    surround = '#' * len(title)
+    # Dashed line long enough to separate, short enough not to get wrapped in terminals.
+    section_sep = '\n\n{}\n\n'.format('-' * 20)
+    return '\n{surround} {title} {surround}\n\n{body}'.format(
+        surround=surround,
+        title=title,
+        body=section_sep.join(
+            '{}: {}'.format(
+                tpl_type.name,
+                # Assuming we only have one Markdown header at the begining of the description, we remove it
+                # for terminal display.
+                tpl_type.description.lstrip("# "),
+            )
+            for tpl_type in VALID_TEMPLATES
+        ),
+    ).rstrip()
+
 
-@click.command(context_settings=CONTEXT_SETTINGS, short_help='Create scaffolding for a new integration')
+@click.command(
+    context_settings=CONTEXT_SETTINGS,
+    # Since we generate the set of valid templates at runtime, describing this set in static docstrings is not ideal.
+    # Click provides a way to generate the description at runtime via the `epilog` option.
+    epilog=_valid_template_description(),
+)
 @click.argument('name')
 @click.option(
     '--type',
     '-t',
     'integration_type',
-    type=click.Choice(get_valid_templates()),
+    type=click.Choice(t.name for t in VALID_TEMPLATES),
     default='check',
-    help='The type of integration to create',
+    help='The type of integration to create. See below for more details.',
 )
 @click.option('--location', '-l', help='The directory where files will be written')
 @click.option('--non-interactive', '-ni', is_flag=True, help='Disable prompting for fields')

datadog_checks_dev/datadog_checks/dev/tooling/create.py

@@ -3,6 +3,7 @@
 # Licensed under a 3-clause BSD style license (see LICENSE)
 import os
 from datetime import datetime
+from operator import attrgetter
 from uuid import uuid4
 
 from ..fs import (
@@ -30,9 +31,25 @@
 EXCLUDE_TEMPLATES = {"marketplace"}
 
 
+class TemplateType(object):
+    def __init__(self, name, templates_dir):
+        self.name = name
+        self.path = os.path.join(templates_dir, name)
+        readme_path = os.path.join(self.path, "README.md")
+        if os.path.exists(readme_path):
+            with open(readme_path) as fh:
+                self.description = fh.read().strip()
+        else:
+            self.description = "No description yet. Please reach out to agent-integrations to add one."
+
+
 def get_valid_templates():
-    templates = [template for template in os.listdir(TEMPLATES_DIR) if template not in EXCLUDE_TEMPLATES]
-    return sorted(templates)
+    templates = [
+        TemplateType(template, TEMPLATES_DIR)
+        for template in os.listdir(TEMPLATES_DIR)
+        if template not in EXCLUDE_TEMPLATES
+    ]
+    return sorted(templates, key=attrgetter('name'))
 
 
 def construct_template_fields(integration_name, repo_choice, integration_type, **kwargs):

datadog_checks_dev/datadog_checks/dev/tooling/templates/integration/check/README.md

@@ -0,0 +1,6 @@
+# Python Agent Check
+
+Also known as an "Agent integration", choose this template type if you need to write Python code to collect data (such as metrics, events, and logs) and submit it to Datadog through the Agent.
+
+It creates a Python package that can be installed on the Agent.
+The changelog is managed with towncrier in integrations-core and manually in other repositories.

datadog_checks_dev/datadog_checks/dev/tooling/templates/integration/logs/README.md

@@ -1,6 +1,6 @@
 # Logs-only Integration
 
-This type of integration only includes logs pipelines and config.
-To help customers get started with their config we turn this integration into a Python package that can be installed in the Agent.
+Choose this type of integration if you only need some pipelines and a configuration for collecting and processing logs through the Agent.
 
-We release these integrations just like real checks and manage the changelog with towncrier in integrations-core.
+To help you get started with your config, this integration is turned into a Python package that can be installed in the Agent.
+These integrations are released just like Agent Checks, and the changelog is managed with towncrier in integrations-core.

datadog_checks_dev/datadog_checks/dev/tooling/templates/integration/metrics_crawler/README.md

@@ -0,0 +1,6 @@
+# Crawler-based Integration
+
+Use this integration type for crawlers that run on Datadog's internal infrastructure.
+
+This type is similar to the `tile` type, but includes boilerplate that's specific to crawlers.
+There is no Python package for this type of integration, it essentially contains a manifest and assets.

datadog_checks_dev/datadog_checks/dev/tooling/templates/integration/tile/README.md

@@ -0,0 +1,5 @@
+# Tile-only Integration
+
+Choose this type of integration if you host the logic in a different repository, and publish only the tile and assets in integrations-core.
+
+Examples of integrations of this type include checks installed on the Agent or crawlers that run on Datadog internal infrastructure.