bug 965335

Resolves unclear formatting of compute extensions documentation at
http://nova.openstack.org/api_ext/index.html

The rst extensions template has been updated to include extension name as
top level hierarchy, and demote all other content.

All existing documentation pages have been reformatted as per the updated
template.

The ext_aggreagates.rst file has also been added to index.rst.

Amendments:
 - Author added to Authors file
 - Typo in ext_volumes.rst fixed

Change-Id: Id67ef91a6e8eaaf4fba46abbd57759c77aaf8991

Authors

@@ -90,6 +90,7 @@ Johannes Erdfelt <johannes.erdfelt@rackspace.com>
 John Dewey <john@dewey.ws>
 John Garbutt <john.garbutt@citrix.com>
 John Griffith <john.griffith@solidfire.com>
+John Kennedy <john.m.kennedy@intel.com>
 John Tran <jtran@attinteractive.com>
 Jonathan Bryce <jbryce@jbryce.com>
 Jordan Rinke <jordan@openstack.org>

doc/source/api_ext/ext_aggregates.rst

@@ -1,6 +1,7 @@
-About This Extension
-====================
-
+The Host Aggregates Extension
+=================================================================
+About this Extension
+--------------------
 This extension introduces the concept of aggregates into Nova. Host aggregates are different from zones and availability zones: while the former allows the partition of Nova deployments into logical groups for load balancing and instance distribution, the latter are for providing some form of physical isolation and redundancy from other availability zones (e.g. by using separate power supply and network gears). Availability zones do not necessarily mean geographic distribution whereas zones usually do. Host aggregates can be regarded as a mechanism to further partitioning an availability zone, i.e. into multiple groups of hosts that share common resources like storage and network. This enables a finer level of granularity in which to structure an entire OpenStack deployment. Aggregates allows higher availability of a single guest instance within an availability zone, it enables advanced VM placement strategies, and more importantly it enables hosts' zero-downtime upgrades (for example, via VM live migration across members of the aggregate, thus causing no disruption to guest instances).
 
 You can use this extension when you have multiple Compute nodes installed (only XenServer/XCP via xenapi driver is currently supported), and you want to leverage the capabilities of the underlying hypervisor resource pools. For example, you want to enable VM live migration (i.e. VM migration within the pool) or enable host maintenance with zero-downtime for guest instances. Please, note that VM migration across pools (i.e. storage migration) is not yet supported in XenServer/XCP, but will be added when available. Bear in mind that the two migration techniques are not mutually exclusive and can be used in combination for a higher level of flexibility in your cloud management.
@@ -12,7 +13,7 @@ Pre-requisites depend on the kind of hypervisor support you are going to use. As
 To obtain current information the extensions available to you, issue an EXTENSION query on the OpenStack system where it is installed, such as http://example.com/v1.1/tenant/extensions.
 
 Extension Overview
-------------------
+~~~~~~~~~~~~~~~~~~
 
 Name
 	Host Aggregates
@@ -45,7 +46,7 @@ Short Description
 	This extension enables the use of hypervisor resource pools in Nova.
 
 Sample Query Responses
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~
 
 As shown below, responses to an EXTENSION query in XML or JSON provide basic information about the extension.
 
@@ -57,23 +58,24 @@ Extension Query Response: JSON::
 
     {"extension": {"updated": "2012-01-12T00:00:00+00:00", "name": "Aggregates", "links": [], "namespace": "http://docs.openstack.org/compute/ext/aggregates/api/v1.1", "alias": "os-aggregates", "description": "Admin-only aggregate administration"}}
 
-
 Document Change History
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
 
 ============= =====================================
 Revision Date Summary of Changes
 2012-02-28    Initial draft
+2012-03-30    Reformat of content
 ============= =====================================
 
 
 Summary of Changes
-==================
+------------------
 This extension to the OpenStack Compute API allows the creation and management of host aggregates (i.e. pools of compute nodes).
 
-New Action
-----------
+This support is provided by the addition of new actions.
 
+New Actions
+~~~~~~~~~~~
 When a new aggregate has been created, actions can be executed using:
 
 	POST /v1.1/<tenant-id>/os-aggregates/<aggregate-id>/action
@@ -101,22 +103,21 @@ For example, to remove a host from an aggregate, the following xml must be submi
 Error Response Code(s) conflict (409), badRequest (400), itemNotFound (404)
 
 New Faults
-----------
+~~~~~~~~~~
 None
 
 New Headers
------------
+~~~~~~~~~~~
 None
 
 New Resources
--------------
+~~~~~~~~~~~~~
 None
 
 New States
-----------
+~~~~~~~~~~
 None
 
 Changes to the Cloud Servers Specification
-------------------------------------------
-
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 None

doc/source/api_ext/ext_config_drive.rst

@@ -1,13 +1,15 @@
-About This Extension
-====================
+The Config Drive Extension
+=================================================================
+About this Extension
+--------------------
 The config-drive extension enables attaching a separate drive to the Compute guest on instance create. It is used with the OpenStack Compute 1.1 API to write configuration data into guest for those guests whose root filesystems cannot be mounted by the Compute host.
 
 To use this extension, you must have installed Compute, with libvirt or Xen using local disk.
 
 To obtain current information the extensions available to you, issue an EXTENSION query on the OpenStack system where it is installed, such as http://example.com/v1.1/tenant/extensions.
 
 Extension Overview
-------------------
+~~~~~~~~~~~~~~~~~~
 
 Name
     Config Drive
@@ -41,7 +43,7 @@ Short Description
 	compute guest on instance create running in an OpenStack cloud.
 
 Sample Query Responses
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~
 
 As shown below, responses to an EXTENSION query in XML or JSON provide basic information about the extension. 
 
@@ -57,35 +59,36 @@ Extension Query Response: JSON::
 
 .. todo:: Provide example of extension query JSON response.
 
-
 Document Change History
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
 
 ============= =====================================
 Revision Date Summary of Changes
 2011-09-16    Initial draft
+2012-03-30    Reformat of content
 ============= =====================================
 
 
 Summary of Changes
-==================
+------------------
 This extension to the OpenStack Compute API allows the addition of a configuration drive to an instance.
 
-New Action
-----------
+This support is provided by the addition of new resources.
+
+New Actions
+~~~~~~~~~~~
 None
 
 New Faults
-----------
-
+~~~~~~~~~~
 None
 
 New Headers
------------
+~~~~~~~~~~~
 None
 
 New Resources
--------------
+~~~~~~~~~~~~~
 This extension to the OpenStack Compute API adds the following resources:
 
 A config_drive attribute to the servers API that is None by default, but can optionally be True or the imageRef of a config-drive image.
@@ -94,10 +97,11 @@ Upon instance create, a guest built with a True config_drive attribute will crea
 Upon instance create, a guest built with an imageRef config_drive attribute will create a local volume from the image.
 
 New States
-----------
+~~~~~~~~~~
+None
 
 Changes to the Cloud Servers Specification
-------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In section 4.1.2 (Create Servers) of the API Specification: Examples 4.3 and 4.4 should optionally add the config-drive attribute as in the below examples:
 

doc/source/api_ext/ext_floating_ip_dns.rst

@@ -1,13 +1,14 @@
-About The Floating IP DNS Extension
-===================================
-
+The Floating IP DNS Extension
+=================================================================
+About this Extension
+--------------------
 The Floating IP DNS extension provides an interface for managing DNS records associated with IP addresses
 allocated by the Floating Ips extension.  Requests are dispatched to a DNS driver selected at startup.
 
 To obtain current information the extensions available to you, issue an EXTENSION query on the OpenStack system where it is installed, such as http://example.com/v1.1/tenant/extension.
 
-Floating IPs Extension Overview
--------------------------------
+Extension Overview
+~~~~~~~~~~~~~~~~~~
 
 Name
         Floating IP DNS
@@ -41,7 +42,7 @@ Short Description
         This extension enables associated DNS entries with floating IPs.
 
 Sample Query Responses
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~
 
 As shown below, responses to an EXTENSION query in XML or JSON provide basic information about the extension.
 
@@ -60,33 +61,35 @@ Extension Query Response: JSON::
         'description': 'Floating IP DNS support'}]}
 
 Document Change History
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
 
 ============= =====================================
 Revision Date Summary of Changes
 2011-12-23    Initial draft
+2012-03-30    Reformat of content
 ============= =====================================
 
 
 Summary of Changes
-==================
+------------------
 This extension to the Compute API enables management of DNS entries for floating IP addresses.
 
-New Action
-----------
+This support is provided by the addition of new resources.
+
+New Actions
+~~~~~~~~~~~
 None
 
 New Faults
-----------
+~~~~~~~~~~
 None
 
 New Headers
------------
+~~~~~~~~~~~
 None
 
 New Resources
--------------
-
+~~~~~~~~~~~~~
 Get a list of registered DNS Domains published by the DNS drivers::
 
     GET /v1.1/<tenant_id>/os-floating-ip-dns/
@@ -191,11 +194,10 @@ Delete a DNS entry::
     Normal Response Code: 200
     Failure Response Code: 404 (Entry to be deleted not found)
 
-
 New States
-----------
+~~~~~~~~~~
 None
 
 Changes to the Cloud Servers Specification
-------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 None

doc/source/api_ext/ext_floating_ips.rst

@@ -1,11 +1,13 @@
-About The Floating IPs Extension
-================================
+The Floating IPs Extension
+=================================================================
+About this Extension
+--------------------
 The Floating IPs extension enables assigning and allocation of floating IP addresses to instances running in an OpenStack cloud. It is used with the OpenStack Compute 1.1 API to add or remove floating IP addresses on named instances. 
 
 To obtain current information the extensions available to you, issue an EXTENSION query on the OpenStack system where it is installed, such as http://example.com/v1.1/tenant/extension.
 
-Floating IPs Extension Overview
--------------------------------
+Extension Overview
+~~~~~~~~~~~~~~~~~~
 
 Name
 	Floating IPs
@@ -38,7 +40,7 @@ Short Description
 	This extension enables assigning floating IP addresses to instances.
 
 Sample Query Responses
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~
 
 As shown below, responses to an EXTENSION query in XML or JSON provide basic information about the extension. 
 
@@ -57,22 +59,23 @@ Extension Query Response: JSON::
 	"description": "Floating IPs support"}]}
 
 Document Change History
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
 
 ============= =====================================
 Revision Date Summary of Changes
 2011-09-14    Initial draft
+2012-03-30    Reformat of content
 ============= =====================================
 
 
 Summary of Changes
-==================
+------------------
 This extension to the Compute API enables support for floating IP addresses.
 
-To support these new actions, the extension also issues new (faults, headers, resources, states, you name it.)
+This support is provided by the addition of new actions and resources.
 
-New Action
-----------
+New Actions
+~~~~~~~~~~~
 This extension uses POST to add or remove floating IP addresses to instances.
 
 Normal Response Code: 202
@@ -84,15 +87,15 @@ removeFloatingIp
 Include the response codes, transitions if applicable, and XML and JSON examples.
 
 New Faults
-----------
+~~~~~~~~~~
 None
 
 New Headers
------------
+~~~~~~~~~~~
 None
 
 New Resources
--------------
+~~~~~~~~~~~~~
 This extension provides an os-floating-ips resource extension to do the following:
 
 List a tenant's floating ips::
@@ -149,11 +152,11 @@ Show a floating ip::
     Normal Response Code: 200
 
 New States
-----------
+~~~~~~~~~~
 None
 
 Changes to the Cloud Servers Specification
-------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 List the specific changes to the API. For example: