Sync heat-translator code

Sync heat-translator code from upstream

JIRA:PARSER-119

Change-Id: I2287b78ad38bc54f7740fd1ee5f08989d5e680bf
Signed-off-by: shangxdy <shang.xiaodong@zte.com.cn>

2 files changed, 44 insertions, 9 deletions

diff --git a/tosca2heat/heat-translator/doc/source/conf.py b/tosca2heat/heat-translator/doc/source/conf.py
index 23aa050..e051aeb 100644
--- a/tosca2heat/heat-translator/doc/source/conf.py
+++ b/tosca2heat/heat-translator/doc/source/conf.py
@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
diff --git a/tosca2heat/heat-translator/doc/source/usage.rst b/tosca2heat/heat-translator/doc/source/usage.rst
index e8f132a..383c696 100644
--- a/tosca2heat/heat-translator/doc/source/usage.rst
+++ b/tosca2heat/heat-translator/doc/source/usage.rst
@@ -12,7 +12,8 @@ Assuming that OpenStackClient (OSC) is available in your environment, you can ea
 
 Alternatively, you can install a particular release of Heat-Translator as available at https://pypi.python.org/pypi/heat-translator.
 
-Once installation is complete, Heat-Translator is ready to use. Currently you can use it in following three ways.
+Once installation is complete, Heat-Translator is ready to use. The only required argument is ``--template-file``. By default, the ``--template-type`` is set to ``tosca`` which is the
+only supported template type at present. Currently you can use Heat-Translator in following three ways.
 
 Translate and get output on command line. For example: ::
 
@@ -39,15 +40,13 @@ Heat-Translator can be used without any specific OpenStack environment set up as
     python heat_translator.py --template-file==<path to the YAML template> --template-type=<type of template e.g. tosca> --parameters="purpose=test"
 
 The heat_translator.py test program is at the root level of the project. The program has currently tested with TOSCA templates.
-It requires two arguments::
-
-1. Path to the file that needs to be translated. The file, flat yaml template or CSAR, can be specified as a local file in your
+The only required argument is ``--template-file``. By default, the ``--template-type`` is set to ``tosca`` which is the only supported template type at present.
+The value to the ``--template-file`` is a path to the file that needs to be translated. The file, flat YAML template or CSAR, can be specified as a local file in your
 system or via URL.
-2. Type of translation (e.g. tosca)
 
 For example, a TOSCA hello world template can be translated by running the following command from the project location::
 
-    python heat_translator.py --template-file=translator/tests/data/tosca_helloworld.yaml --template-type=tosca
+    python heat_translator.py --template-file=translator/tests/data/tosca_helloworld.yaml
 
 This should produce a translated Heat Orchestration Template on the command line. The translated content can be saved to a desired file by setting --output-file=<path>.
 For example: ::
@@ -57,7 +56,7 @@ For example: ::
 An optional argument can be provided to handle user inputs parameters. Also, a template file can only be validated instead of translation by using --validate-only=true
 optional argument. The command below shows an example usage::
 
-    python heat_translator.py --template-file==<path to the YAML template> --template-type=<type of template e.g. tosca> --validate-only=true
+    python heat_translator.py --template-file=<path to the YAML template> --template-type=<type of template e.g. tosca> --validate-only=true
 
 Alternatively, you can install a particular release of Heat-Translator as available at https://pypi.python.org/pypi/heat-translator.
 In this case, you can simply run translation via CLI entry point::
@@ -79,4 +78,41 @@ Things To Consider
   capabilities. However, user may required to use these properties in template in certain circumstances, so in that case, TOSCA Compute can be extended
   with these properties and later used in the node template. For a good example, refer to the ``translator/tests/data/test_tosca_flavor_and_image.yaml`` test
   template.
-
+* The Heat-Translator can be used to automatically deploy translated TOSCA template given that your environment has python-heatclient and python-keystoneclient.
+  This can be achieved by providing ``--deploy`` argument to the Heat-Translator. You can provide desired stack name by providing it as ``--stack-name <name>``
+  argument. If you do not provide ``--stack-name``, an unique name will be created and used.
+  Below is an example command to deploy translated template with a desired stack name::
+      heat-translator --template-file translator/tests/data/tosca_helloworld.yaml --stack-name mystack --deploy
+* The Heat-Translator supports translation of TOSCA templates to Heat Senlin
+  resources (e.g. ``OS::Senlin::Cluster``) but that requires to use a specific
+  TOSCA node type called ``tosca.policies.Scaling.Cluster``.
+  The ``tosca.policies.Scaling.Cluster`` is a custom type that derives from
+  ``tosca.policies.Scaling``. For example usage, refer to the
+  ``tosca_cluster_autoscaling.yaml`` and ``hot_cluster_autoscaling.yaml``
+  provided under the ``translator/tests/data/autoscaling`` and
+  ``translator/tests/data/hot_output/autoscaling`` directories respectively in
+  the heat-translator project (``https://github.com/openstack/heat-translator``).
+  When you use ``tosca.policies.Scaling`` normative node type, the
+  Heat-Translator will translate it to ``OS::Heat::AutoScalingGroup`` Heat
+  resource. Related example templates, ``tosca_autoscaling.yaml`` and
+  ``hot_autoscaling.yaml`` can be found for reference purposes under the same
+  directory structure mentioned above.
+* With the version 0.7.0 of Heat-Translator, output of multiple template files
+  (for example, nested templates in autoscaling) can be accessed via newly
+  introduced API called ``translate_to_yaml_files_dict(<output_filename>)``
+  where ``<output_filename>`` is the name of file where you want to store parent
+  HOT template. The return value of this API call will be a dictionary in HOT
+  YAML with one or multiple file names as keys and translated content as values.
+  In order to use this on the command line, simply invoke Heat-Translator with
+  ``--output-file`` argument. Here, the parent template will be stored in the
+  value specified to the ``--output-file``. Whereas, child templates, if any,
+  will be saved at the same location of the parent template.
+
+  Below is an example of how to call the API in your code, where
+  ``translator`` is an instance of Heat-Translator::
+
+      yaml_files = translator.translate_to_yaml_files_dict(filename)
+
+  Below is an example of how to use this on the command line::
+
+      heat-translator --template-file translator/tests/data/autoscaling/tosca_autoscaling.yaml --output-file /tmp/hot.yaml
\ No newline at end of file