From 4b578db8fb1ed28087ca04892be6148dc9cab0ce Mon Sep 17 00:00:00 2001 From: Angus Salkeld Date: Thu, 22 Aug 2013 12:27:21 +1000 Subject: [PATCH] Fix all the sphinx-build warnings except this one: WARNING: toctree contains reference to nonexisting document u'api/autoindex' Change-Id: I176a75c1c3fc9603304f11f867df54d7a7b3610a --- doc/source/architecture.rst | 10 +-- doc/source/index.rst | 2 +- doc/source/template_guide/functions.rst | 12 ++-- doc/source/template_guide/hot_guide.rst | 14 ++-- doc/source/template_guide/hot_spec.rst | 8 +-- .../cfn/WordPress_Single_Instance.rst | 70 +++++++++---------- doc/source/templates/hot/hello_world.rst | 30 ++++---- 7 files changed, 76 insertions(+), 70 deletions(-) diff --git a/doc/source/architecture.rst b/doc/source/architecture.rst index 005fb8ef3c..533f706c17 100644 --- a/doc/source/architecture.rst +++ b/doc/source/architecture.rst @@ -26,12 +26,12 @@ Detailed Description What is the purpose of the project and vision for it? -*Heat provides an AWS CloudFormation implementation for OpenStack that orchestrates an AWS CloudFormation template describing a cloud application by executing appropriate OpenStack API calls to generate running cloud applications. +*Heat provides an AWS CloudFormation implementation for OpenStack that orchestrates an AWS CloudFormation template describing a cloud application by executing appropriate OpenStack API calls to generate running cloud applications.* Describe the relevance of the project to other OpenStack projects and the OpenStack mission to provide a ubiquitous cloud computing platform: -*The software integrates other core components of OpenStack into a one-file template system. The templates allow creation of most OpenStack resource types (such as instances, floating ips, volumes, security groups, users, etc), as well as some more advanced functionality such as instance high availability, instance autoscaling, and nested stacks. By providing very tight integration with other OpenStack core projects, all OpenStack core projects could receive a larger user base. -*Currently no other CloudFormation implementation exists for OpenStack. The developers believe cloud developers have a strong desire to move workloads from AWS to OpenStack deployments. Given the missing gap of a well-implemented and integrated CloudFormation API in OpenStack, we provide a high quality implementation of this gap improving the ubiquity of OpenStack. +*The software integrates other core components of OpenStack into a one-file template system. The templates allow creation of most OpenStack resource types (such as instances, floating ips, volumes, security groups, users, etc), as well as some more advanced functionality such as instance high availability, instance autoscaling, and nested stacks. By providing very tight integration with other OpenStack core projects, all OpenStack core projects could receive a larger user base.* +*Currently no other CloudFormation implementation exists for OpenStack. The developers believe cloud developers have a strong desire to move workloads from AWS to OpenStack deployments. Given the missing gap of a well-implemented and integrated CloudFormation API in OpenStack, we provide a high quality implementation of this gap improving the ubiquity of OpenStack.* ------------- Heat Services @@ -42,7 +42,7 @@ The developers are focused on creating an OpenStack style project using OpenStac As the developers have only started development in March 2012, the architecture is evolving rapidly. heat ------ +---- The heat tool is a CLI which communicates with the heat-api to execute AWS CloudFormation APIs. End developers could also use the heat REST API directly. @@ -64,4 +64,4 @@ heat-engine The heat engine's main responsibility is to orchestrate the launching of templates and provide events back to the API consumer. -The templates integrate well with .. _Puppet: https://s3.amazonaws.com/cloudformation-examples/IntegratingAWSCloudFormationWithPuppet.pdf and .. _Chef: http://www.full360.com/2011/02/27/integrating-aws-cloudformation-and-chef.html \ No newline at end of file +The templates integrate well with .. _Puppet: https://s3.amazonaws.com/cloudformation-examples/IntegratingAWSCloudFormationWithPuppet.pdf and .. _Chef: http://www.full360.com/2011/02/27/integrating-aws-cloudformation-and-chef.html diff --git a/doc/source/index.rst b/doc/source/index.rst index b3a2102740..90b40ca998 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -34,7 +34,7 @@ Getting Started :maxdepth: 1 getting_started/index - troubleshooting/index + templates/index template_guide/index glossary diff --git a/doc/source/template_guide/functions.rst b/doc/source/template_guide/functions.rst index 3758a16b4e..48ae20a265 100644 --- a/doc/source/template_guide/functions.rst +++ b/doc/source/template_guide/functions.rst @@ -10,6 +10,7 @@ WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. + ================== Built in functions ================== @@ -64,13 +65,13 @@ Mappings section. Parameters ~~~~~~~~~~ map_name : String - The logical name of a mapping declared in the Mappings section that + The logical name of a mapping declared in the Mappings section that contains the keys and values. top_level_key : String The top-level key name. It's value is a list of key-value pairs. -second_level_key : String +second_level_key : String The second-level key name, which is set to one of the keys from the list assigned to top_level_key. @@ -162,8 +163,8 @@ Select an item from a list. Parameters ~~~~~~~~~~ selector : string or integer - The number of item in the list or the name of the item in -the map. + The number of item in the list or the name of the item in the map. + collection : map or list The collection to select the item from. @@ -174,12 +175,14 @@ For a list lookup: :: { "Fn::Select" : [ "2", [ "apples", "grapes", "mangoes" ] ] } + Returns ``mangoes`` For a map lookup: :: { "Fn::Select" : [ "red", {"red": "a", "flu": "b"} ] } + Returns ``a`` --------- @@ -219,6 +222,7 @@ string: String Usage ~~~~~ :: + {"Fn::Replace": [ {'$var1': 'foo', '%var2%': 'bar'}, '$var1 is %var2%' diff --git a/doc/source/template_guide/hot_guide.rst b/doc/source/template_guide/hot_guide.rst index ece38d6680..a711584536 100644 --- a/doc/source/template_guide/hot_guide.rst +++ b/doc/source/template_guide/hot_guide.rst @@ -11,6 +11,8 @@ License for the specific language governing permissions and limitations under the License. +.. _hot_guide: + ======================================= Heat Orchestration Template (HOT) Guide ======================================= @@ -19,7 +21,7 @@ HOT is a new template format meant to replace the Heat CloudFormation-compatible format (CFN) as the native format supported by the Heat over time. This guide is targeted towards template authors and explains how to write HOT templates based on examples. A detailed specification of HOT can be found -at :ref:`_hot_spec`. +at :ref:`hot_spec`. ------ Status @@ -83,7 +85,7 @@ set of *input parameters* instead of hard-coding such values. Template input parameters ------------------------- Input parameters defined in the *parameters* section of a HOT template (see also -:ref:`_hot_spec_parameters`) allow users to customize a template during +:ref:`hot_spec_parameters`) allow users to customize a template during deployment. For example, this allows for providing custom key-pair names or image IDs to be used for a deployment. From a template author's perspective, this helps to make a template more easily @@ -123,7 +125,7 @@ In the example above, three input parameters have been defined that have to be provided by the user upon deployment. The fixed values for the respective resource properties have been replaced by references to the corresponding input parameters by means of the *get_param* function (see also -:ref:`_hot_spec_intrinsic_functions`). +:ref:`hot_spec_intrinsic_functions`). You can also define default values for input parameters which will be used in case the user does not provide the respective parameter during deployment. For @@ -159,7 +161,7 @@ users can supply. For example, you might know that the software running in a compute instance needs a certain amount of resources so you might want to restrict the *instance_type* parameter introduced above. Parameters in HOT templates can be restricted by adding a *constraints* section (see also -:ref:`_hot_spec_parameters_constraints`). +:ref:`hot_spec_parameters_constraints`). For example, the following would allow only three values to be provided as input for the *instance_type* parameter: @@ -203,7 +205,7 @@ Providing template outputs -------------------------- In addition to template customization through input parameters, you will typically want to provide outputs to users, which can be done in the -*outputs* section of a template (see also :ref:`_hot_spec_outputs`). +*outputs* section of a template (see also :ref:`hot_spec_outputs`). For example, the IP address by which the instance defined in the example above can be accessed should be provided to users. Otherwise, users would have to look it up themselves. The definition for providing the IP address of the @@ -218,4 +220,4 @@ compute instance as an output is shown in the following snippet: Output values are typically resolved using intrinsic function such as the *get_attr* function in the example above (see also -:ref:`_hot_spec_intrinsic_functions`). +:ref:`hot_spec_intrinsic_functions`). diff --git a/doc/source/template_guide/hot_spec.rst b/doc/source/template_guide/hot_spec.rst index 55d8f913da..a8fca8d000 100644 --- a/doc/source/template_guide/hot_spec.rst +++ b/doc/source/template_guide/hot_spec.rst @@ -21,7 +21,7 @@ HOT is a new template format meant to replace the Heat CloudFormation-compatible format (CFN) as the native format supported by the Heat over time. This specification explains in detail all elements of the HOT template format. An example driven guide to writing HOT templates can be found -at :ref:`_hot_guide`. +at :ref:`hot_guide`. ------ Status @@ -320,7 +320,7 @@ type properties This section contains a list of resource specific properties. The property value can be provided in place, or can be provided via a function - (see :ref:`_hot_spec_intrinsic_functions`). + (see :ref:`hot_spec_intrinsic_functions`). Depending on the type of resource, the resource block might include more resource specific metadata. Basically all resource types that can be used in @@ -363,7 +363,7 @@ parameter value This element specifies the value of the output parameter. Typically, this will be resolved by means of a function, e.g. by getting an attribute value of one of the stack's resources (see also - :ref:`_hot_spec_intrinsic_functions`). + :ref:`hot_spec_intrinsic_functions`). The example below shows, how the public IP address of a compute resource can be defined as an output parameter. @@ -427,7 +427,7 @@ The syntax of the get_attr function is as follows: resource ID This parameter specifies the resource the attribute of which shall be resolved. This resource must be defined within the *resources* section of - the template (see also :ref:`_hot_spec_resources`). + the template (see also :ref:`hot_spec_resources`). attribute name This parameter specifies the attribute to be resolved. diff --git a/doc/source/templates/cfn/WordPress_Single_Instance.rst b/doc/source/templates/cfn/WordPress_Single_Instance.rst index c56259319d..5a2d035212 100644 --- a/doc/source/templates/cfn/WordPress_Single_Instance.rst +++ b/doc/source/templates/cfn/WordPress_Single_Instance.rst @@ -22,38 +22,38 @@ AWS CloudFormation Sample Template WordPress_Single_Instance: WordPress is web s Parameters ---------- -*KeyName :mod:`(required)` - *type - *string - *description - *Name of an existing key pair to use for the instance -*InstanceType :mod:`(optional)` - *type - *string - *description - *Instance type for the instance to be created -*DBName :mod:`(optional)` - *type - *string - *description - *The WordPress database name -*DBUsernameName :mod:`(optional)` - *type - *string - *description - *The WordPress database admin account username -*DBPassword :mod:`(optional)` - *type - *string - *description - *The WordPress database admin account password -*DBRootPassword :mod:`(optional)` - *type - *string - *description - *Root password for MySQL -*LinuxDistribution :mod:`(optional)` - *type - *string - *description - *Distribution of choice \ No newline at end of file +*KeyName* :mod:`(required)` + *type* + *string* + *description* + *Name* of an existing key pair to use for the instance +*InstanceType* :mod:`(optional)` + *type* + *string* + *description* + *Instance type* for the instance to be created +*DBName* :mod:`(optional)` + *type* + *string* + *description* + *The WordPress database name* +*DBUsernameName* :mod:`(optional)` + *type* + *string* + *description* + *The WordPress database admin account username* +*DBPassword* :mod:`(optional)` + *type* + *string* + *description* + *The WordPress database admin account password* +*DBRootPassword* :mod:`(optional)` + *type* + *string* + *description* + *Root password for MySQL* +*LinuxDistribution* :mod:`(optional)` + *type* + *string* + *description* + *Distribution of choice* diff --git a/doc/source/templates/hot/hello_world.rst b/doc/source/templates/hot/hello_world.rst index d08c75ee76..9ee65796cf 100644 --- a/doc/source/templates/hot/hello_world.rst +++ b/doc/source/templates/hot/hello_world.rst @@ -23,18 +23,18 @@ Description Parameters ---------- -*KeyName :mod:`(required)` - *type - *string - *description - *Name of an existing key pair to use for the instance -*InstanceType :mod:`(required)` - *type - *string - *description - *Instance type for the instance to be created -*ImageId :mod:`(required)` - *type - *string - *description - *ID of the image to use for the instance \ No newline at end of file +*KeyName* :mod:`(required)` + *type* + *string* + *description* + *Name* of an existing key pair to use for the instance +*InstanceType* :mod:`(required)` + *type* + *string* + *description* + *Instance type* for the instance to be created +*ImageId* :mod:`(required)` + *type* + *string* + *description* + *ID* of the image to use for the instance