From e9707af332057bd16c5ea7198274cc07034b6675 Mon Sep 17 00:00:00 2001 From: Steve Baker Date: Mon, 24 Aug 2015 11:43:48 +1200 Subject: [PATCH] Use code-block:: yaml for all template snippets This replaces any existing literal blocks containing template snippets with a yaml highlighted code block, which is more consistent with newer content. The resource HOT Syntax generation is also fixed to use yaml syntax highlighting by setting the rawsource argument Change-Id: Ie3404420ef70eba6402a4f7171cc56fb5a1f9445 --- doc/source/ext/resources.py | 2 +- doc/source/template_guide/composition.rst | 24 ++- doc/source/template_guide/functions.rst | 39 +++-- doc/source/template_guide/hot_guide.rst | 16 +- doc/source/template_guide/hot_spec.rst | 178 ++++++++++++++++------ 5 files changed, 180 insertions(+), 79 deletions(-) diff --git a/doc/source/ext/resources.py b/doc/source/ext/resources.py index d3cce091b..4594d99e3 100644 --- a/doc/source/ext/resources.py +++ b/doc/source/ext/resources.py @@ -176,7 +176,7 @@ resources: the_resource: type: %s%s''' % (self.resource_type, props_str) - block = nodes.literal_block('', template, language="hot") + block = nodes.literal_block(template, template, language="yaml") section.append(block) @staticmethod diff --git a/doc/source/template_guide/composition.rst b/doc/source/template_guide/composition.rst index 5095615fe..d508a010e 100644 --- a/doc/source/template_guide/composition.rst +++ b/doc/source/template_guide/composition.rst @@ -42,7 +42,9 @@ To achieve this: The following examples illustrate how you can use a custom template to define new types of resources. These examples use a custom template stored in a -:file:`my_nova.yaml` file:: +:file:`my_nova.yaml` file + +.. code-block:: yaml heat_template_version: 2014-10-16 @@ -62,7 +64,9 @@ new types of resources. These examples use a custom template stored in a Use the template filename as type ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following template defines the :file:`my_nova.yaml` file as value for the -``type`` property of a resource:: +``type`` property of a resource + +.. code-block:: yaml heat_template_version: 2014-10-16 @@ -99,7 +103,9 @@ resource will override the default one. In the following example a new ``OS::Nova::Server`` resource overrides the default resource of the same name. -An :file:`env.yaml` environment file holds the definition of the new resource:: +An :file:`env.yaml` environment file holds the definition of the new resource + +.. code-block:: yaml resource_registry: "OS::Nova::Server": my_nova.yaml @@ -108,7 +114,9 @@ An :file:`env.yaml` environment file holds the definition of the new resource:: See :ref:`environments` for more detail about environment files. -You can now use the new ``OS::Nova::Server`` in your new template:: +You can now use the new ``OS::Nova::Server`` in your new template + +.. code-block:: yaml heat_template_version: 2014-10-16 @@ -126,7 +134,9 @@ Get access to nested attributes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ There are implicit attributes of a template resource. Accessing nested attributes requires ``heat_template_version`` 2014-10-16 or higher. These are -accessible as follows:: +accessible as follows + +.. code-block:: yaml heat_template_version: 2014-10-16 @@ -146,7 +156,9 @@ Making your template resource more "transparent" If you wish to be able to return the ID of one of the inner resources instead of the nested stack's identifier, you can add the special reserved -output ``OS::stack_id`` to your template resource:: +output ``OS::stack_id`` to your template resource + +.. code-block:: yaml heat_template_version: 2014-10-16 diff --git a/doc/source/template_guide/functions.rst b/doc/source/template_guide/functions.rst index 790aa80ee..4d147ed6e 100644 --- a/doc/source/template_guide/functions.rst +++ b/doc/source/template_guide/functions.rst @@ -35,7 +35,8 @@ name : String Usage ~~~~~ -:: + +.. code-block:: yaml {Ref: my_server} @@ -57,7 +58,7 @@ value : String Usage ~~~~~ -:: +.. code-block:: yaml {"Fn::Base64": "convert this string please."} @@ -85,7 +86,7 @@ second_level_key : String Usage ~~~~~ -:: +.. code-block:: yaml Mapping: MyContacts: @@ -112,7 +113,7 @@ attribute : String Usage ~~~~~ -:: +.. code-block:: yaml {Fn::GetAtt: [my_server, PublicIp]} @@ -132,7 +133,8 @@ region : String Usage ~~~~~ -:: + +.. code-block:: yaml {Fn::GetAZs: ""} @@ -154,7 +156,7 @@ list : list Usage ~~~~~ -:: +.. code-block:: yaml {Fn::Join: [",", ["beer", "wine", "more beer"]]} @@ -179,14 +181,16 @@ Usage ~~~~~ For a list lookup: -:: + +.. code-block:: yaml { "Fn::Select" : [ "2", [ "apples", "grapes", "mangoes" ] ] } Returns ``mangoes``. For a map lookup: -:: + +.. code-block:: yaml { "Fn::Select" : [ "red", {"red": "a", "flu": "b"} ] } @@ -208,7 +212,8 @@ string : String Usage ~~~~~ -:: + +.. code-block:: yaml { "Fn::Split" : [ ",", "str1,str2,str3,str4"]} @@ -228,7 +233,8 @@ string: String Usage ~~~~~ -:: + +.. code-block:: yaml {"Fn::Replace": [ {'$var1': 'foo', '%var2%': 'bar'}, @@ -254,7 +260,7 @@ attribute_name : String Usage ~~~~~ -:: +.. code-block:: yaml {'Fn::ResourceFacade': 'Metadata'} {'Fn::ResourceFacade': 'DeletionPolicy'} @@ -265,7 +271,7 @@ Example ~~~~~~~ Here is a top level template ``top.yaml`` -:: +.. code-block:: yaml resources: my_server: @@ -276,7 +282,8 @@ Here is a top level template ``top.yaml`` Here is a resource template ``my_actual_server.yaml`` -:: + +.. code-block:: yaml resources: _actual_server_: @@ -284,7 +291,8 @@ Here is a resource template ``my_actual_server.yaml`` metadata: {'Fn::ResourceFacade': Metadata} The environment file ``env.yaml`` -:: + +.. code-block:: yaml resource_registry: resources: @@ -320,7 +328,8 @@ list: A list of strings Usage ~~~~~ -:: + +.. code-block:: yaml {'Fn::MemberListToMap': ['Name', 'Value', ['.member.0.Name=key', '.member.0.Value=door', diff --git a/doc/source/template_guide/hot_guide.rst b/doc/source/template_guide/hot_guide.rst index 6b452129b..c99de2ff2 100644 --- a/doc/source/template_guide/hot_guide.rst +++ b/doc/source/template_guide/hot_guide.rst @@ -46,7 +46,7 @@ definition using only predefined properties (along with the mandatory Heat template version tag). For example, the template below could be used to simply deploy a single compute instance. -:: +.. code-block:: yaml heat_template_version: 2013-05-23 @@ -66,7 +66,7 @@ it is good practice to include some useful text that describes what users can do with the template. In case you want to provide a longer description that does not fit on a single line, you can provide multi-line text in YAML, for example: -:: +.. code-block:: yaml description: > This is how you can provide a longer description @@ -96,7 +96,7 @@ their custom key-pairs, provide their own image, and to select a flavor for the compute instance. This can be achieved by extending the initial template as follows: -:: +.. code-block:: yaml heat_template_version: 2013-05-23 @@ -135,7 +135,7 @@ case the user does not provide the respective parameter during deployment. For example, the following definition for the *instance_type* parameter would select the 'm1.small' flavor unless specified otherwise by the user. -:: +.. code-block:: yaml parameters: instance_type: @@ -149,7 +149,7 @@ users request information about a stack deployed from a template. This is achieved by the *hidden* attribute and useful, for example when requesting passwords as user input: -:: +.. code-block:: yaml parameters: database_password: @@ -170,7 +170,7 @@ templates can be restricted by adding a *constraints* section (see also For example, the following would allow only three values to be provided as input for the *instance_type* parameter: -:: +.. code-block:: yaml parameters: instance_type: @@ -186,7 +186,7 @@ all be fulfilled by user input. For example, the following list of constraints could be used to clearly specify format requirements on a password to be provided by users: -:: +.. code-block:: yaml parameters: database_password: @@ -218,7 +218,7 @@ 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 compute instance as an output is shown in the following snippet: -:: +.. code-block:: yaml outputs: instance_ip: diff --git a/doc/source/template_guide/hot_spec.rst b/doc/source/template_guide/hot_spec.rst index ca0f88d0f..e13cec425 100644 --- a/doc/source/template_guide/hot_spec.rst +++ b/doc/source/template_guide/hot_spec.rst @@ -41,7 +41,7 @@ Template structure HOT templates are defined in YAML and follow the structure outlined below. -:: +.. code-block:: yaml heat_template_version: 2013-05-23 @@ -160,9 +160,7 @@ For example, Heat currently supports the following values for the The key with value ``2015-10-15`` indicates that the YAML document is a HOT template and it may contain features added and/or removed up until the Liberty release. This version removes the *Fn::Select* function, path based - ``get_attr``/``get_param`` references should be used instead. - -:: + ``get_attr``/``get_param`` references should be used instead:: get_attr get_file @@ -190,7 +188,7 @@ parameters. Each parameter should be associated to a specific group only once using the parameter name to bind it to a defined parameter in the ``parameters`` section. -:: +.. code-block:: yaml parameter_groups: - label: @@ -228,7 +226,7 @@ Each parameter is specified in a separated nested block with the name of the parameters defined in the first line and additional attributes such as type or default value defined as nested elements. -:: +.. code-block:: yaml parameters: : @@ -300,7 +298,9 @@ The table below describes all currently supported types with examples: | | false value. | | +----------------------+-------------------------------+------------------+ -The following example shows a minimalistic definition of two parameters:: +The following example shows a minimalistic definition of two parameters + +.. code-block:: yaml parameters: user_name: @@ -326,7 +326,9 @@ The ``constraints`` block of a parameter definition defines additional validation constraints that apply to the value of the parameter. The parameter values provided by a user are validated against the constraints at instantiation time. The constraints are defined as a list with -the following syntax:: +the following syntax + +.. code-block:: yaml constraints: - : @@ -351,7 +353,7 @@ constraints. Note that while the descriptions for each constraint are optional, it is good practice to provide concrete descriptions to present useful messages to the user at deployment time. -:: +.. code-block:: yaml parameters: user_name: @@ -378,7 +380,9 @@ The ``length`` constraint applies to parameters of type ``string``. It defines a lower and upper limit for the length of the string value. -The syntax of the ``length`` constraint is:: +The syntax of the ``length`` constraint is + +.. code-block:: yaml length: { min: , max: } @@ -391,7 +395,9 @@ The ``range`` constraint applies to parameters of type ``number``. It defines a lower and upper limit for the numeric value of the parameter. -The syntax of the ``range`` constraint is:: +The syntax of the ``range`` constraint is + +.. code-block:: yaml range: { min: , max: } @@ -400,7 +406,9 @@ upper limit. However, at least one of ``min`` or ``max`` must be specified. The minimum and maximum boundaries are included in the range. For example, the following range constraint would allow for all numeric values between 0 and -10:: +10 + +.. code-block:: yaml range: { min: 0, max: 10 } @@ -412,18 +420,24 @@ The ``allowed_values`` constraint applies to parameters of type parameter. At deployment time, the user-provided value for the respective parameter must match one of the elements of the list. -The syntax of the ``allowed_values`` constraint is:: +The syntax of the ``allowed_values`` constraint is + +.. code-block:: yaml allowed_values: [ , , ... ] -Alternatively, the following YAML list notation can be used:: +Alternatively, the following YAML list notation can be used + +.. code-block:: yaml allowed_values: - - - ... -For example:: +For example + +.. code-block:: yaml parameters: instance_type: @@ -442,11 +456,15 @@ The ``allowed_pattern`` constraint applies to parameters of type ``string``. It specifies a regular expression against which a user-provided parameter value must evaluate at deployment. -The syntax of the ``allowed_pattern`` constraint is:: +The syntax of the ``allowed_pattern`` constraint is + +.. code-block:: yaml allowed_pattern: -For example:: +For example + +.. code-block:: yaml parameters: user_name: @@ -465,7 +483,9 @@ generally to check that the specified resource exists in the backend. Custom constraints get implemented by plug-ins and can provide any kind of advanced constraint validation logic. -The syntax of the ``custom_constraint`` constraint is:: +The syntax of the ``custom_constraint`` constraint is + +.. code-block:: yaml custom_constraint: @@ -473,7 +493,9 @@ The ``name`` attribute specifies the concrete type of custom constraint. It corresponds to the name under which the respective validation plugin has been registered in the Orchestration engine. -For example:: +For example + +.. code-block:: yaml parameters: key_name @@ -509,7 +531,9 @@ deployed from the HOT template (for instance compute instances, networks, storage volumes). Each resource is defined as a separate block in the ``resources`` section with -the following syntax:: +the following syntax + +.. code-block:: yaml resources: : @@ -562,7 +586,9 @@ All resource types that can be used in CFN templates can also be used in HOT templates, adapted to the YAML structure as outlined above. The following example demonstrates the definition of a simple compute resource -with some fixed property values:: +with some fixed property values + +.. code-block:: yaml resources: my_instance: @@ -581,7 +607,9 @@ resource and one or more other resources. If a resource depends on just one other resource, the ID of the other resource is specified as string of the ``depends_on`` attribute, as shown in the -following example:: +following example + +.. code-block:: yaml resources: server1: @@ -593,7 +621,9 @@ following example:: If a resource depends on more than one other resources, the value of the ``depends_on`` attribute is specified as a list of resource IDs, as shown in -the following example:: +the following example + +.. code-block:: yaml resources: server1: @@ -617,7 +647,9 @@ such as IP addresses of deployed instances, or URLs of web applications deployed as part of a stack. Each output parameter is defined as a separate block within the outputs section -according to the following syntax:: +according to the following syntax + +.. code-block:: yaml outputs: : @@ -639,7 +671,9 @@ parameter value This attribute is required. The example below shows how the IP address of a compute resource can -be defined as an output parameter:: +be defined as an output parameter + +.. code-block:: yaml outputs: instance_ip: @@ -669,7 +703,9 @@ instance created from the respective resource definition. Path based attribute referencing using keys or indexes requires ``heat_template_version`` ``2014-10-16`` or higher. -The syntax of the ``get_attr`` function is:: +The syntax of the ``get_attr`` function is + +.. code-block:: yaml get_attr: - @@ -689,7 +725,9 @@ attribute name specified. These additional parameters are used to navigate the data structure to return the desired value. -The following example demonstrates how to use the :code:`get_attr` function:: +The following example demonstrates how to use the :code:`get_attr` function + +.. code-block:: yaml resources: my_instance: @@ -719,7 +757,9 @@ The ``get_file`` function returns the content of a file into the template. It is generally used as a file inclusion mechanism for files containing scripts or configuration files. -The syntax of ``get_file`` function is:: +The syntax of ``get_file`` function is + +.. code-block:: yaml get_file: @@ -737,7 +777,9 @@ to the absolute URLs required by the Orchestration API. engine). The example below demonstrates the ``get_file`` function usage with both -relative and absolute URLs:: +relative and absolute URLs + +.. code-block:: yaml resources: my_instance: @@ -765,7 +807,9 @@ get_param The ``get_param`` function references an input parameter of a template. It resolves to the value provided for this input parameter at runtime. -The syntax of the ``get_param`` function is:: +The syntax of the ``get_param`` function is + +.. code-block:: yaml get_param: - @@ -779,7 +823,9 @@ parameter name specified. These additional parameters are used to navigate the data structure to return the desired value. -The following example demonstrates the use of the ``get_param`` function:: +The following example demonstrates the use of the ``get_param`` function + +.. code-block:: yaml parameters: instance_type: @@ -815,14 +861,18 @@ The ``get_resource`` function references another resource within the same template. At runtime, it is resolved to reference the ID of the referenced resource, which is resource type specific. For example, a reference to a floating IP resource returns the respective IP address at runtime. The syntax -of the ``get_resource`` function is:: +of the ``get_resource`` function is + +.. code-block:: yaml get_resource: The resource ID of the referenced resource is given as single parameter to the ``get_resource`` function. -For example:: +For example + +.. code-block:: yaml resources: instance_port: @@ -841,13 +891,17 @@ list_join --------- The ``list_join`` function joins a list of strings with the given delimiter. -The syntax of the ``list_join`` function is:: +The syntax of the ``list_join`` function is + +.. code-block:: yaml list_join: - - -For example:: +For example + +.. code-block:: yaml list_join: [', ', ['one', 'two', 'and three']] @@ -860,7 +914,9 @@ The ``digest`` function allows for performing digest operations on a given value. This function has been introduced in the Kilo release and is usable with HOT versions later than ``2015-04-30``. -The syntax of the ``digest`` function is:: +The syntax of the ``digest`` function is + +.. code-block:: yaml digest: - @@ -875,7 +931,9 @@ value of the value. -For example:: +For example + +.. code-block:: yaml # from a user supplied parameter pwd_hash: { digest: ['sha512', { get_param: raw_password }] } @@ -891,7 +949,9 @@ over the contents of one or more source lists and replacing the list elements into a template. The result of this function is a new list, where the elements are set to the template, rendered for each list item. -The syntax of the ``repeat`` function is:: +The syntax of the ``repeat`` function is + +.. code-block:: yaml repeat: template: @@ -916,7 +976,9 @@ for_each dictionary can be given as functions such as ``get_attr`` or ``get_param``. The following example shows how a security group resource can be defined to -include a list of ports given as a parameter:: +include a list of ports given as a parameter + +.. code-block:: yaml parameters: ports: @@ -939,7 +1001,9 @@ include a list of ports given as a parameter:: port_range_max: %port% The following example demonstrates how the use of multiple lists enables the -security group to also include parameterized protocols:: +security group to also include parameterized protocols + +.. code-block:: yaml parameters: ports: @@ -976,7 +1040,9 @@ provider template. A provider template provides a custom definition of a resource, called its facade. For more information about custom templates, see :ref:`composition`. -The syntax of the ``resource_facade`` function is:: +The syntax of the ``resource_facade`` function is + +.. code-block:: yaml resource_facade: @@ -991,7 +1057,9 @@ providing a template string with placeholders and a list of mappings to assign values to those placeholders at runtime. The placeholders are replaced with mapping values wherever a mapping key exactly matches a placeholder. -The syntax of the ``str_replace`` function is:: +The syntax of the ``str_replace`` function is + +.. code-block:: yaml str_replace: template: