From adee53a2ee041381511b31163b4a53e7665e1420 Mon Sep 17 00:00:00 2001
From: Steve Baker <sbaker@redhat.com>
Date: Sat, 27 Jul 2013 11:40:50 +1200
Subject: [PATCH] Use subsections in resource doc generation.

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
---
 heat/doc/resources.py | 43 +++++++++++++++++++++++--------------------
 1 file changed, 23 insertions(+), 20 deletions(-)

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