Move doc template into packaged file, format improvements

cloudbender/__init__.py

@@ -2,7 +2,7 @@ import logging
 
 __author__ = "Stefan Reimer"
 __email__ = "stefan@zero-downtimet.net"
-__version__ = "0.8.4"
+__version__ = "0.8.5"
 
 
 # Set up logging to ``/dev/null`` like a library is supposed to.

cloudbender/stack.py

@@ -20,6 +20,12 @@ from .exceptions import ParameterNotFound, ParameterIllegalValue
 
 import cfnlint.core
 
+try:
+    import importlib.resources as pkg_resources
+except ImportError:
+    import importlib_resources as pkg_resources
+from . import templates
+
 import logging
 logger = logging.getLogger(__name__)
 
@@ -316,7 +322,7 @@ class Stack(object):
         except ClientError as e:
             raise e
 
-    def create_docs(self):
+    def create_docs(self, template=False):
         """ Read template, parse documentation fragments, eg. parameter description
             and create a mardown doc file for the stack
             same idea as eg. helm-docs for values.yaml
@@ -324,31 +330,13 @@ class Stack(object):
 
         self.read_template_file()
 
-        doc_template = """
+        if not template:
-{{ name }}
+            doc_template = pkg_resources.read_text(templates, 'stack-doc.md')
-===
+            jenv = JinjaEnv()
-{{ description }}
+            template = jenv.from_string(doc_template)
-
+            data = {}
-{% if dependencies %}
+        else:
-## Dependencies
+            doc_template = template
-{% for d in dependencies|sort %}
-- {{ d }}
-{% endfor %}
-{% endif %}
-
-{% if parameters %}
-## Parameters
-| Parameter | Type | Default | Format | Description |
-|-----------|------|---------|--------|-------------|
-{% for p in parameters.keys() %}
-| {{ p }} | {{ parameters[p]['Type'] }} | {{ parameters[p]['Default'] }} | {{ parameters[p]['AllowedValues'] or parameters[p]['AllowedPattern']}} | {{ parameters[p]['Description'] }} |
-{% endfor %}
-{% endif %}
-"""
-
-        jenv = JinjaEnv()
-        template = jenv.from_string(doc_template)
-        data = {}
 
         data['name'] = self.stackname
         data['description'] = self.cfn_data['Description']

cloudbender/templates/stack-doc.md

@@ -0,0 +1,27 @@
+{{ name }}
+===
+{{ description }}
+
+{% if dependencies %}
+## Dependencies
+{% for d in dependencies|sort %}
+- {{ d }}
+{% endfor %}
+{% endif %}
+
+{% if parameters %}
+## Parameters
+| Parameter | Type | Default | Format | Description |
+|-----------|------|---------|--------|-------------|
+{% for p in parameters.keys() %}
+{% if parameters[p]['AllowedValues'] or parameters[p]['AllowedPattern'] %}
+{% set format = '`%s%s`' % (parameters[p]['AllowedValues'], parameters[p]['AllowedPattern']) %}
+{% endif %}
+{% if parameters[p]['Default'] and parameters[p]['Type'].lower() == "string" %}
+{% set def = '`"%s"`' % parameters[p]['Default'] %}
+{% else %}
+{% set def = parameters[p]['Default'] %}
+{% endif %}
+| {{ p }} | {{ parameters[p]['Type'] | lower }} | {{ def }} | {{ format }} | {{ parameters[p]['Description'] }} |
+{% endfor %}
+{% endif %}

setup.py

@@ -53,6 +53,7 @@ setup(
     author_email='stefan@zero-downtime.net',
     url='https://git.zero-downtime.net/ZeroDownTime/CloudBender',
     packages=find_packages(),
+    package_data={ 'cloudbender': ['templates/*.md'], },
     include_package_data=True,
     entry_points={'console_scripts': [ "cloudbender = cloudbender.cli:cli" ]},
     install_requires=['boto3', 'Jinja2', 'oyaml', 'click', 'cfn-lint', 'pyminifier'],