Improve resource types list rendering

https://docs.openstack.org/heat/latest/template_guide/openstack.html
looks a bit messy right now, this tries to make some improvements:
 * Reduce the TOC depth
 * Improve version messages
 * Indent property description
 * Fix map/list properties rendering

Change-Id: I1571d1af9eba2619f8db64c54ad0b141b354a524
This commit is contained in:
Thomas Herve 2018-07-23 18:18:05 +02:00
parent bea5084ea8
commit 81e1acfe72
5 changed files with 64 additions and 25 deletions

View File

@ -13,6 +13,7 @@
# -*- coding: utf-8 -*-
from functools import cmp_to_key
import json
import pydoc
from docutils import core
@ -130,8 +131,17 @@ class ResourcePages(rst.Directive):
'status_msg': sstatus['message']}
if not (sstatus['status'] == support.SUPPORTED and
sstatus['version'] is None):
para = nodes.paragraph('', msg)
note = nodes.note('', para)
para = nodes.inline('', msg)
para['classes'] = ['versionmodified']
parent_para = nodes.paragraph()
parent_para['classes'] = ['versionsupport']
parent_para.append(para)
note = nodes.topic()
if sstatus['status'] == support.SUPPORTED:
note['classes'] = ['versionadded']
else:
note['classes'] = ['deprecated']
note.append(parent_para)
section.append(note)
support_status = support_status.previous_status
@ -143,6 +153,23 @@ class ResourcePages(rst.Directive):
section.append(title)
return section
def _prop_section(self, parent, title, id_pattern):
id = id_pattern % self.resource_type
section = nodes.section(ids=[id])
parent.append(section)
# Ignore title generated for list items
if title != '*':
title = nodes.term('', title)
ref = nodes.reference('', u'\xb6')
ref['classes'] = ['headerlink']
ref['refid'] = id
title.append(ref)
section.append(title)
field = nodes.definition()
section.append(field)
return field
def _prop_syntax_example(self, prop):
if not prop:
return 'Value'
@ -209,78 +236,80 @@ resources:
id_pattern_prefix = '%s-prop'
id_pattern = id_pattern_prefix + '-' + prop_key
definition = self._section(parent, prop_key, id_pattern)
definition = self._prop_section(parent, prop_key, id_pattern)
self._status_str(prop.support_status, definition)
if not prop.implemented:
para = nodes.paragraph('', _('Not implemented.'))
para = nodes.line('', _('Not implemented.'))
note = nodes.note('', para)
definition.append(note)
return
if sub_prop and prop.type != properties.Schema.LIST and prop.type\
!= properties.Schema.MAP:
if sub_prop and prop.type not in (properties.Schema.LIST,
properties.Schema.MAP):
if prop.required:
para = nodes.paragraph('', _('Required.'))
para = nodes.line('', _('Required.'))
definition.append(para)
else:
para = nodes.paragraph('', _('Optional.'))
para = nodes.line('', _('Optional.'))
definition.append(para)
if prop.description:
para = nodes.paragraph('', prop.description)
para = nodes.line('', prop.description)
definition.append(para)
type = nodes.paragraph('', _('%s value expected.') % prop.type)
type = nodes.line('', _('%s value expected.') % prop.type)
definition.append(type)
if upd_para is not None:
definition.append(upd_para)
else:
if prop.update_allowed:
upd_para = nodes.paragraph(
upd_para = nodes.line(
'', _('Can be updated without replacement.'))
definition.append(upd_para)
elif prop.immutable:
upd_para = nodes.paragraph('', _('Updates are not supported. '
'Resource update will fail on'
' any attempt to update this '
'property.'))
upd_para = nodes.line('', _('Updates are not supported. '
'Resource update will fail on '
'any attempt to update this '
'property.'))
definition.append(upd_para)
else:
upd_para = nodes.paragraph('', _('Updates cause replacement.'))
upd_para = nodes.line('', _('Updates cause replacement.'))
definition.append(upd_para)
if prop.default is not None:
para = nodes.paragraph('', _('Defaults to "%s".') % prop.default)
para = nodes.line('', _('Defaults to '))
default = nodes.literal('', json.dumps(prop.default))
para.append(default)
definition.append(para)
for constraint in prop.constraints:
para = nodes.paragraph('', str(constraint))
para = nodes.line('', str(constraint))
definition.append(para)
sub_schema = None
if prop.schema and prop.type == properties.Schema.MAP:
para = nodes.paragraph()
para = nodes.line()
emph = nodes.emphasis('', _('Map properties:'))
para.append(emph)
definition.append(para)
sub_schema = prop.schema
elif prop.schema and prop.type == properties.Schema.LIST:
para = nodes.paragraph()
para = nodes.line()
emph = nodes.emphasis('', _('List contents:'))
para.append(emph)
definition.append(para)
sub_schema = prop.schema
if sub_schema:
indent = nodes.definition_list()
definition.append(indent)
for _key, _prop in sorted(sub_schema.items(),
key=cmp_to_key(self.cmp_prop)):
if _prop.support_status.status != support.HIDDEN:
indent = nodes.block_quote()
definition.append(indent)
self.contribute_property(
indent, _key, _prop, upd_para, id_pattern,
sub_prop=True)
@ -297,20 +326,24 @@ resources:
if required_props:
section = self._section(
parent, _('Required Properties'), '%s-props-req')
definition_list = nodes.definition_list()
section.append(definition_list)
for prop_key, prop in sorted(required_props.items(),
key=cmp_to_key(self.cmp_prop)):
self.contribute_property(section, prop_key, prop)
self.contribute_property(definition_list, prop_key, prop)
optional_props = dict((k, v) for k, v in props.items()
if not v.required)
if optional_props:
section = self._section(
parent, _('Optional Properties'), '%s-props-opt')
definition_list = nodes.definition_list()
section.append(definition_list)
for prop_key, prop in sorted(optional_props.items(),
key=cmp_to_key(self.cmp_prop)):
self.contribute_property(section, prop_key, prop)
self.contribute_property(definition_list, prop_key, prop)
def contribute_attributes(self, parent):
if not self.attrs_schemata:
@ -319,7 +352,7 @@ resources:
for prop_key, prop in sorted(self.attrs_schemata.items()):
if prop.support_status.status != support.HIDDEN:
description = prop.description
attr_section = self._section(
attr_section = self._prop_section(
section, prop_key, '%s-attr-' + prop_key)
self._status_str(prop.support_status, attr_section)

View File

@ -11,6 +11,8 @@
License for the specific language governing permissions and limitations
under the License.
:tocdepth: 2
CloudFormation Compatible Resource Types
----------------------------------------
.. integratedrespages:: AWS::

View File

@ -11,6 +11,8 @@
License for the specific language governing permissions and limitations
under the License.
:tocdepth: 2
Contributed Heat Resource Types
===============================

View File

@ -11,6 +11,7 @@
License for the specific language governing permissions and limitations
under the License.
:tocdepth: 2
OpenStack Resource Types
------------------------

View File

@ -11,6 +11,7 @@
License for the specific language governing permissions and limitations
under the License.
:tocdepth: 2
Unsupported Heat Resource Types
===============================