openstack
/
heat
Code Issues Proposed changes

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
This commit is contained in:
Gauvain Pocentek 2014-09-04 15:01:28 +02:00
parent 68f78c8edb
commit 0a99bf8fc3
1 changed files with 41 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
doc/source/ext/resources.py
View File

@ -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()
msg = _('%(status)s')
if sstatus['message'] is not None:
msg = _('%(status)s - %(message)s')
para = nodes.inline('', msg % sstatus)
warning = nodes.note('', para)
section.append(warning)
para = nodes.paragraph('', self._status_str(
resource_class.support_status))
note = nodes.note('', para)
section.append(note)
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()
msg = _('%(status)s')
if sstatus['message'] is not None:
msg = _('%(status)s - %(message)s')
para = nodes.inline('', msg % sstatus)
warning = nodes.note('', para)
definition.append(warning)
para = nodes.paragraph('', self._status_str(prop.support_status))
note = nodes.note('', para)
definition.append(note)
if not prop.implemented:
para = nodes.inline('', _('Not implemented.'))
warning = nodes.note('', para)
definition.append(warning)
para = nodes.paragraph('', _('Not implemented.'))
note = nodes.note('', para)
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()
msg = _('%(status)s')
if sstatus['message'] is not None:
msg = _('%(status)s - %(message)s')
para = nodes.inline('', msg % sstatus)
warning = nodes.note('', para)
definition.append(warning)
para = nodes.paragraph('',
self._status_str(prop.support_status))
note = nodes.note('', para)
definition.append(note)
if description:
def_para = nodes.paragraph('', description)