openstack/deb-heat
Code Issues Proposed changes

Use subsections in resource doc generation.

Browse Source 
This allows any part of the resource type documentation
to be hyperlinked to.

Properties and attributes have also been moved above the syntax
examples.

Change-Id: Ie0fa2a1134be283a6c99ac2effcc869304d28f09
This commit is contained in:
Steve Baker 2013-07-27 11:40:50 +12:00
parent c1be1264b9
commit adee53a2ee
1 changed files with 23 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
heat/doc/resources.py
View File

@ -39,26 +39,30 @@ class ResourcePages(Directive):
for resource_type, resource_class in _all_resources(prefix): for resource_type, resource_class in _all_resources(prefix):
self.resource_type = resource_type self.resource_type = resource_type
self.resource_class = resource_class self.resource_class = resource_class
resourceid = 'resource-%s' % resource_type section = self._section(content, resource_type, '%s')
section = nodes.section(ids=[resourceid])
content.append(section)
title = nodes.title('', resource_type)
section.append(title)
cls_doc = resource_class.__doc__ cls_doc = resource_class.__doc__
if cls_doc: if cls_doc:
para = nodes.paragraph('', cls_doc) para = nodes.paragraph('', cls_doc)
section.append(para) section.append(para)
self.contribute_hot_syntax(section)
self.contribute_yaml_syntax(section)
self.contribute_json_syntax(section)
self.contribute_properties(section) self.contribute_properties(section)
self.contribute_attributes(section) self.contribute_attributes(section)
self.contribute_hot_syntax(section)
self.contribute_yaml_syntax(section)
self.contribute_json_syntax(section)
return content return content
def _section(self, parent, title, id_pattern):
id = id_pattern % self.resource_type
section = nodes.section(ids=[id])
parent.append(section)
title = nodes.title('', title)
section.append(title)
return section
def _prop_syntax_example(self, prop): def _prop_syntax_example(self, prop):
if not prop or not prop.get('Type'): if not prop or not prop.get('Type'):
return 'Value' return 'Value'
@ -78,8 +82,8 @@ class ResourcePages(Directive):
else: else:
return prop_type return prop_type
def contribute_hot_syntax(self, section): def contribute_hot_syntax(self, parent):
section.append(nodes.strong('', _('HOT Syntax'))) section = self._section(parent, _('HOT Syntax'), '%s-hot')
schema = self.resource_class.properties_schema schema = self.resource_class.properties_schema
props = [] props = []
for prop_key in sorted(schema.keys()): for prop_key in sorted(schema.keys()):
@ -99,8 +103,8 @@ resources:
block = nodes.literal_block('', template) block = nodes.literal_block('', template)
section.append(block) section.append(block)
def contribute_yaml_syntax(self, section): def contribute_yaml_syntax(self, parent):
section.append(nodes.strong('', _('YAML Syntax'))) section = self._section(parent, _('YAML Syntax'), '%s-yaml')
schema = self.resource_class.properties_schema schema = self.resource_class.properties_schema
props = [] props = []
for prop_key in sorted(schema.keys()): for prop_key in sorted(schema.keys()):
@ -120,8 +124,8 @@ Resources:
block = nodes.literal_block('', template) block = nodes.literal_block('', template)
section.append(block) section.append(block)
def contribute_json_syntax(self, section): def contribute_json_syntax(self, parent):
section.append(nodes.strong('', _('JSON Syntax'))) section = self._section(parent, _('JSON Syntax'), '%s-json')
schema = self.resource_class.properties_schema schema = self.resource_class.properties_schema
props = [] props = []
@ -216,11 +220,11 @@ Resources:
sub_prop = sub_schema[sub_prop_key] sub_prop = sub_schema[sub_prop_key]
self.contribute_property(sub_prop_list, sub_prop_key, sub_prop) self.contribute_property(sub_prop_list, sub_prop_key, sub_prop)
def contribute_properties(self, section): def contribute_properties(self, parent):
schema = self.resource_class.properties_schema schema = self.resource_class.properties_schema
if not schema: if not schema:
return return
section.append(nodes.strong('', _('Properties'))) section = self._section(parent, _('Properties'), '%s-props')
prop_list = nodes.definition_list() prop_list = nodes.definition_list()
section.append(prop_list) section.append(prop_list)
for prop_key in sorted(schema.keys()): for prop_key in sorted(schema.keys()):
@ -228,12 +232,11 @@ Resources:
self.contribute_property(prop_list, prop_key, prop) self.contribute_property(prop_list, prop_key, prop)
def contribute_attributes(self, section): def contribute_attributes(self, parent):
schema = self.resource_class.attributes_schema schema = self.resource_class.attributes_schema
if not schema: if not schema:
return return
section = self._section(parent, _('Attributes'), '%s-attrs')
section.append(nodes.strong('', _('Attributes')))
prop_list = nodes.definition_list() prop_list = nodes.definition_list()
section.append(prop_list) section.append(prop_list)
for prop_key in sorted(schema.keys()): for prop_key in sorted(schema.keys()):