openstack/deb-heat
Code Issues Proposed changes

Use sections for individual properties and attributes

Browse Source 
It is often helpful to point people at the documentation
for a specific attribute or property. This change achieves
this by using sections instead if definition items to
format the documentation of a property/attribute.

Complex property schemas are indented using block quotes
and the fragment identifier is appended to so that each
link is unique. (eg, #OS::Ceilometer::Alarm-prop-query-*-field)

The 'required' and 'optional' sections have been brought up one
level, replacing 'Properties' with 'Required Properties' and
'Optional Properties'.

Closes-Bug: #1486429
Change-Id: Ifd497aac74e8aff76ea91a295df17bb1da949ba8
This commit is contained in:
Steve Baker 2015-08-25 10:08:54 +12:00
parent 569bd15521
commit 25f707cdf0
1 changed files with 39 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -12,11 +12,10 @@
# under the License. # under the License.
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
import itertools import pydoc
from docutils import core from docutils import core
from docutils import nodes from docutils import nodes
import pydoc
import six import six
from sphinx.util import compat from sphinx.util import compat
@ -192,15 +191,13 @@ resources:
return cmp(x_prop.support_status.status, return cmp(x_prop.support_status.status,
y_prop.support_status.status) y_prop.support_status.status)
def contribute_property(self, prop_list, prop_key, prop, upd_para=None): def contribute_property(self, parent, prop_key, prop, upd_para=None,
prop_item = nodes.definition_list_item( id_pattern_prefix=None):
'', nodes.term('', prop_key)) if not id_pattern_prefix:
prop_list.append(prop_item) id_pattern_prefix = '%s-prop'
id_pattern = id_pattern_prefix + '-' + prop_key
prop_item.append(nodes.classifier('', prop.type)) definition = self._section(parent, prop_key, id_pattern)
definition = nodes.definition()
prop_item.append(definition)
self._status_str(prop.support_status, definition) self._status_str(prop.support_status, definition)
@ -214,6 +211,9 @@ resources:
para = nodes.paragraph('', prop.description) para = nodes.paragraph('', prop.description)
definition.append(para) definition.append(para)
type = nodes.paragraph('', _('%s value expected.') % prop.type)
definition.append(type)
if upd_para is not None: if upd_para is not None:
definition.append(upd_para) definition.append(upd_para)
else: else:
@ -255,68 +255,64 @@ resources:
sub_schema = prop.schema sub_schema = prop.schema
if sub_schema: if sub_schema:
sub_prop_list = nodes.definition_list()
definition.append(sub_prop_list)
for sub_prop_key, sub_prop in sorted(sub_schema.items(), for sub_prop_key, sub_prop in sorted(sub_schema.items(),
self.cmp_prop): self.cmp_prop):
if sub_prop.support_status.status != support.HIDDEN: if sub_prop.support_status.status != support.HIDDEN:
indent = nodes.block_quote()
definition.append(indent)
self.contribute_property( self.contribute_property(
sub_prop_list, sub_prop_key, sub_prop, upd_para) indent, sub_prop_key, sub_prop, upd_para, id_pattern)
def contribute_properties(self, parent): def contribute_properties(self, parent):
if not self.props_schemata: if not self.props_schemata:
return return
section = self._section(parent, _('Properties'), '%s-props')
prop_list_required = nodes.definition_list()
subsection_required = self._section(section, _('required'),
'%s-props-req')
subsection_required.append(prop_list_required)
prop_list_optional = nodes.definition_list() props = dict((k, v) for k, v in self.props_schemata.items()
subsection_optional = self._section(section, _('optional'), if v.support_status.status != support.HIDDEN)
'%s-props-opt')
subsection_optional.append(prop_list_optional)
for prop_key, prop in sorted(self.props_schemata.items(), required_props = dict((k, v) for k, v in props.items()
if v.required)
if required_props:
section = self._section(
parent, _('Required Properties'), '%s-props-req')
for prop_key, prop in sorted(required_props.items(),
self.cmp_prop): self.cmp_prop):
if prop.support_status.status != support.HIDDEN: self.contribute_property(section, prop_key, prop)
if prop.required:
prop_list = prop_list_required optional_props = dict((k, v) for k, v in props.items()
else: if not v.required)
prop_list = prop_list_optional if optional_props:
self.contribute_property(prop_list, prop_key, prop) section = self._section(
parent, _('Optional Properties'), '%s-props-opt')
for prop_key, prop in sorted(optional_props.items(),
self.cmp_prop):
self.contribute_property(section, prop_key, prop)
def contribute_attributes(self, parent): def contribute_attributes(self, parent):
if not self.attrs_schemata: if not self.attrs_schemata:
return return
section = self._section(parent, _('Attributes'), '%s-attrs') section = self._section(parent, _('Attributes'), '%s-attrs')
prop_list = nodes.definition_list()
section.append(prop_list)
for prop_key, prop in sorted(self.attrs_schemata.items()): for prop_key, prop in sorted(self.attrs_schemata.items()):
if prop.support_status.status != support.HIDDEN: if prop.support_status.status != support.HIDDEN:
description = prop.description description = prop.description
prop_item = nodes.definition_list_item( attr_section = self._section(
'', nodes.term('', prop_key)) section, prop_key, '%s-attr-' + prop_key)
prop_list.append(prop_item)
definition = nodes.definition() self._status_str(prop.support_status, attr_section)
prop_item.append(definition)
self._status_str(prop.support_status, definition)
if description: if description:
def_para = nodes.paragraph('', description) def_para = nodes.paragraph('', description)
definition.append(def_para) attr_section.append(def_para)
def contribute_update_policy(self, parent): def contribute_update_policy(self, parent):
if not self.update_policy_schemata: if not self.update_policy_schemata:
return return
section = self._section(parent, _('UpdatePolicy'), '%s-updpolicy') section = self._section(parent, _('UpdatePolicy'), '%s-updpolicy')
prop_list = nodes.definition_list()
section.append(prop_list)
for prop_key, prop in sorted(self.update_policy_schemata.items(), for prop_key, prop in sorted(self.update_policy_schemata.items(),
self.cmp_prop): self.cmp_prop):
self.contribute_property(prop_list, prop_key, prop) self.contribute_property(section, prop_key, prop)
class IntegrateResourcePages(ResourcePages): class IntegrateResourcePages(ResourcePages):