5 files changed, 201 insertions, 0 deletions
diff --git a/tosca2heat/heat-translator/doc/source/conf.py b/tosca2heat/heat-translator/doc/source/conf.py
new file mode 100644
index 0000000..23aa050
--- /dev/null
+++ b/tosca2heat/heat-translator/doc/source/conf.py
@@ -0,0 +1,75 @@
+# -*- 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
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('../..'))
+# -- General configuration ----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    #'sphinx.ext.intersphinx',
+    'oslosphinx'
+]
+
+# autodoc generation is a bit aggressive and a nuisance when doing heavy
+# text edit cycles.
+# execute "export SPHINX_DEBUG=1" in your terminal to disable
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'heat-translator'
+copyright = u'2013, OpenStack Foundation'
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = True
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# -- Options for HTML output --------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+# html_theme_path = ["."]
+# html_theme = 'default'
+# html_static_path = ['static']
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = '%sdoc' % project
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass
+# [howto/manual]).
+latex_documents = [
+    ('index',
+     '%s.tex' % project,
+     u'%s Documentation' % project,
+     u'OpenStack Foundation', 'manual'),
+]
+
+# Example configuration for intersphinx: refer to the Python standard library.
+#intersphinx_mapping = {'http://docs.python.org/': None}
diff --git a/tosca2heat/heat-translator/doc/source/contributing.rst b/tosca2heat/heat-translator/doc/source/contributing.rst
new file mode 100644
index 0000000..8cb3146
--- /dev/null
+++ b/tosca2heat/heat-translator/doc/source/contributing.rst
@@ -0,0 +1 @@
+.. include:: ../../CONTRIBUTING.rst
+\ No newline at end of file
diff --git a/tosca2heat/heat-translator/doc/source/index.rst b/tosca2heat/heat-translator/doc/source/index.rst
new file mode 100644
index 0000000..dd3f04f
--- /dev/null
+++ b/tosca2heat/heat-translator/doc/source/index.rst
@@ -0,0 +1,29 @@
+.. heat-translator documentation master file, created by
+   sphinx-quickstart on Tue Jul  9 22:26:36 2013.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to heat-translator's documentation!
+===========================================
+
+The heat-translator tool is aimed to translate non-heat templates to OpenStack
+Heat Orchestration Template (HOT). Initially the tool is aimed to translate
+OASIS Topology and Orchestration Specification for Cloud Applications (TOSCA)
+to HOT. However, the tool can be easily extended to support any non-heat
+template format to produce HOT.
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   installation
+   usage
+   contributing
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/tosca2heat/heat-translator/doc/source/installation.rst b/tosca2heat/heat-translator/doc/source/installation.rst
new file mode 100644
index 0000000..71c5237
--- /dev/null
+++ b/tosca2heat/heat-translator/doc/source/installation.rst
@@ -0,0 +1,15 @@
+============
+Installation
+============
+
+Assuming that OpenStackClient (OSC) is available in your environment, you can easily install Heat-Translator to use with OSC by following three steps::
+
+    git clone https://github.com/openstack/heat-translator
+    cd heat-translator
+    sudo python setup.py install
+
+You can also clone the project and use it without any specific OpenStack environment set up as below::
+
+    git clone https://github.com/openstack/heat-translator
+
+Heat-Translator can be installed via PyPI package as well. Refer to https://pypi.python.org/pypi/heat-translator for available packages.
diff --git a/tosca2heat/heat-translator/doc/source/usage.rst b/tosca2heat/heat-translator/doc/source/usage.rst
new file mode 100644
index 0000000..ebad0e8
--- /dev/null
+++ b/tosca2heat/heat-translator/doc/source/usage.rst
@@ -0,0 +1,81 @@
+=====
+Usage
+=====
+
+Use Heat-Translator with OpenStackClient (OSC)
+----------------------------------------------
+Assuming that OpenStackClient (OSC) is available in your environment, you can easily install Heat-Translator to use with OSC by following three steps::
+
+    git clone https://github.com/openstack/heat-translator
+    cd heat-translator
+    sudo python setup.py install
+
+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.
+
+Translate and get output on command line. For example: ::
+
+    openstack translate template --template-file /home/openstack/heat-translator/translator/tests/data/tosca_helloworld.yaml --template-type tosca
+
+Translate and save output of translated file to a desired destination. For example: ::
+
+    openstack translate template --template-file /home/openstack/heat-translator/translator/tests/data/tosca_helloworld.yaml --template-type tosca --output-file /tmp/hot_hello_world.yaml
+
+Do not translate but only validate template file. For example: ::
+
+    openstack translate template --template-file /home/openstack/heat-translator/translator/tests/data/tosca_helloworld.yaml --template-type tosca --validate-only=true
+
+You can learn more about available options by running following help command::
+
+    openstack help translate template
+
+
+Use Heat-Translator on its own
+------------------------------
+Heat-Translator can be used without any specific OpenStack environment set up as below::
+
+    git clone https://github.com/openstack/heat-translator
+    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
+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
+
+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: ::
+
+    python heat_translator.py --template-file=translator/tests/data/tosca_helloworld.yaml --template-type=tosca --output-file=/tmp/hot_helloworld.yaml
+
+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
+
+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::
+    heat-translator --template-file=translator/tests/data/tosca_helloworld.yaml --template-type=tosca
+
+Things To Consider
+------------------
+* When deploying the translated template with Heat, please ensure that you have image registered in the Glance. The Heat-Translator
+  project sets flavor and image from a pre-defined set of values (as listed in /home/openstack/heat-translator/translator/hot/tosca/tosca_compute.py)
+  with the best possible match to the constraints defined in the TOSCA template. If there is no possible match found, a null value is set currently.
+  Per the future plan, an image and flavor will be provided from an online repository.
+* The ``key_name`` property of Nova server is irrelevant to the TOSCA specification and can not be used in TOSCA template. In order to use it in
+  the translated templates, the user must provide it via parameters, and the heat-translator will set it to all resources of ``OS::Nova::Server`` type.
+* Since properties of TOSCA Compute OS and HOST capabilities are optional, the user should make sure that either they set these properties correctly
+  in the TOSCA template or provide them via CLI parameters in order to find best match of flavor and image.
+* The ``flavor`` and ``image`` properties of ``OS::Nova::Server`` resource is irrelevant to the TOSCA specification and can not be used in the TOSCA
+  template as such. Heat-Translator sets these properties in the translated template based on constraints defined per TOSCA Compute OS and HOST
+  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.
+