doc: Improve use of the support_status attribute

This patch adds admonitions to the template_guide to indicate support
status of resources to the reader. Deprecated resources will be clearly
indicated, as well as the version in which a resource appeared.

This patch also rework the generated markup to use paragraph nodes
instead of inline nodes inside notes.

Closes-Bug: #1360561
Change-Id: I5ee9fd47f0aa9627beb842dc46aa3bac10060e13

doc/source/ext/resources.py

@@ -27,6 +27,9 @@ from heat.engine import properties
 from heat.engine import resources
 from heat.engine import support
 
+_CODE_NAMES = {'2014.1': 'Icehouse',
+               '2014.2': 'Juno',
+               '2015.1': 'Kilo'}
 
 global_env = environment.Environment({}, user_env=False)
 
@@ -56,13 +59,10 @@ class ResourcePages(Directive):
                 self.resource_class.attributes_schema)
 
             if resource_class.support_status.status == support.DEPRECATED:
-                sstatus = resource_class.support_status.to_dict()
+                para = nodes.paragraph('', self._status_str(
-                msg = _('%(status)s')
+                                       resource_class.support_status))
-                if sstatus['message'] is not None:
+                note = nodes.note('', para)
-                    msg = _('%(status)s - %(message)s')
+                section.append(note)
-                para = nodes.inline('', msg % sstatus)
-                warning = nodes.note('', para)
-                section.append(warning)
 
             cls_doc = pydoc.getdoc(resource_class)
             if cls_doc:
@@ -70,6 +70,13 @@ class ResourcePages(Directive):
                 cls_nodes = core.publish_doctree(cls_doc).children
                 section.extend(cls_nodes)
 
+            if (resource_class.support_status.status == support.SUPPORTED and
+               resource_class.support_status.version is not None):
+                tag = resource_class.support_status.version.title()
+                message = (_('Available since %s.') % self._version_str(tag))
+                para = nodes.paragraph('', message)
+                section.append(para)
+
             self.contribute_properties(section)
             self.contribute_attributes(section)
 
@@ -79,6 +86,23 @@ class ResourcePages(Directive):
 
         return content
 
+    def _version_str(self, version):
+        if version in _CODE_NAMES:
+            return "%(version)s (%(code)s)" % {'version': version,
+                                               'code': _CODE_NAMES[version]}
+        else:
+            return version
+
+    def _status_str(self, support_status):
+        sstatus = support_status.to_dict()
+        msg = sstatus['status']
+        if sstatus['version'] is not None:
+            msg += ' since %s' % self._version_str(sstatus['version'])
+        if sstatus['message'] is not None:
+            msg += ' - %s' % sstatus['message']
+
+        return msg
+
     def _section(self, parent, title, id_pattern):
         id = id_pattern % self.resource_type
         section = nodes.section(ids=[id])
@@ -209,18 +233,14 @@ Resources:
         prop_item.append(definition)
 
         if prop.support_status.status != support.SUPPORTED:
-            sstatus = prop.support_status.to_dict()
+            para = nodes.paragraph('', self._status_str(prop.support_status))
-            msg = _('%(status)s')
+            note = nodes.note('', para)
-            if sstatus['message'] is not None:
+            definition.append(note)
-                msg = _('%(status)s - %(message)s')
-            para = nodes.inline('', msg % sstatus)
-            warning = nodes.note('', para)
-            definition.append(warning)
 
         if not prop.implemented:
-            para = nodes.inline('', _('Not implemented.'))
+            para = nodes.paragraph('', _('Not implemented.'))
-            warning = nodes.note('', para)
+            note = nodes.note('', para)
-            definition.append(warning)
+            definition.append(note)
             return
 
         if prop.description:
@@ -304,13 +324,10 @@ Resources:
             prop_item.append(definition)
 
             if prop.support_status.status != support.SUPPORTED:
-                sstatus = prop.support_status.to_dict()
+                para = nodes.paragraph('',
-                msg = _('%(status)s')
+                                       self._status_str(prop.support_status))
-                if sstatus['message'] is not None:
+                note = nodes.note('', para)
-                    msg = _('%(status)s - %(message)s')
+                definition.append(note)
-                para = nodes.inline('', msg % sstatus)
-                warning = nodes.note('', para)
-                definition.append(warning)
 
             if description:
                 def_para = nodes.paragraph('', description)