4 files changed, 112 insertions, 18 deletions
diff --git a/tosca2heat/heat-translator/README.md b/tosca2heat/heat-translator/README.md
new file mode 100644
index 0000000..c8af42a
--- /dev/null
+++ b/tosca2heat/heat-translator/README.md
@@ -0,0 +1,56 @@
+========================
+Team and repository tags
+========================
+
+.. image:: http://governance.openstack.org/badges/heat-translator.svg
+    :target: http://governance.openstack.org/reference/tags/index.html
+
+.. Change things from this point on
+
+===============
+Heat-Translator
+===============
+
+Overview
+--------
+
+Heat-Translator is an Openstack project and licensed under Apache 2. It is a
+command line tool which takes non-Heat templates as an input and produces a
+Heat Orchestration Template (HOT) which can be deployed by Heat. Currently the
+development and testing is done with an aim to translate OASIS Topology and
+Orchestration Specification for Cloud Applications (TOSCA) templates to
+HOT. However, the tool is designed to be easily extended to use with any
+format other than TOSCA.
+
+Architecture
+------------
+
+Heat-Translator project takes a non-Heat template (e.g. TOSCA flat YAML
+template or template embedded in TOSCA Cloud Service Archive (CSAR) format) as
+an input, calls an appropriate Parser (e.g. TOSCA Parser) per the type of input
+template to parse it and create an in-memory graph, maps it to Heat resources
+and then produces a Heat Orchestration Template (HOT) as an output.
+
+How To Use
+----------
+Please refer to `doc/source/usage.rst <https://github.com/openstack/heat-translator/blob/master/doc/source/usage.rst>`_
+
+Directory Structure
+-------------------
+
+Three main directories related to the heat-translator are:
+
+1. hot: It is the generator, that has logic of converting TOSCA in memory graph to HOT YAML files.
+2. common: It has all the file that can support the execution of parser and generator.
+3. tests: It contains test programs and more importantly several templates which are used for testing.
+
+Project Info
+------------
+
+* License: Apache License, Version 2.0
+* Documentation: http://docs.openstack.org/developer/heat-translator/
+* Launchpad: https://launchpad.net/heat-translator
+* Blueprints: https://blueprints.launchpad.net/heat-translator
+* Bugs: https://bugs.launchpad.net/heat-translator
+* Source: http://git.openstack.org/cgit/openstack/heat-translator/
+* IRC Channel: #openstack-heat-translator
diff --git a/tosca2heat/heat-translator/setup.cfg b/tosca2heat/heat-translator/setup.cfg
index 21d0c6f..38bc1b9 100644
--- a/tosca2heat/heat-translator/setup.cfg
+++ b/tosca2heat/heat-translator/setup.cfg
@@ -2,7 +2,7 @@
 name = heat-translator
 summary = Tool to translate non-heat templates to Heat Orchestration Template.
 description-file =
-    README.rst
+    README.md
 author = OpenStack
 author-email = openstack-dev@lists.openstack.org
 home-page = http://docs.openstack.org/developer/heat-translator/
@@ -35,14 +35,6 @@ openstack.translator.v1 =
 console_scripts =
     heat-translator = translator.shell:main
 
-[build_sphinx]
-source-dir = doc/source
-build-dir = doc/build
-all_files = 1
-
-[upload_sphinx]
-upload-dir = doc/build/html
-
 [compile_catalog]
 directory = translator/locale
 domain = translator
diff --git a/tosca2heat/tosca-parser/README.md b/tosca2heat/tosca-parser/README.md
new file mode 100644
index 0000000..0f94072
--- /dev/null
+++ b/tosca2heat/tosca-parser/README.md
@@ -0,0 +1,54 @@
+========================
+Team and repository tags
+========================
+
+.. image:: http://governance.openstack.org/badges/tosca-parser.svg
+    :target: http://governance.openstack.org/reference/tags/index.html
+
+.. Change things from this point on
+
+===============
+TOSCA Parser
+===============
+
+Overview
+--------
+
+The TOSCA Parser is an OpenStack project and licensed under Apache 2. It is
+developed to parse TOSCA Simple Profile in YAML. It reads the TOSCA templates
+and creates an in-memory graph of TOSCA nodes and their relationship.
+
+Architecture
+------------
+
+The TOSCA Parser takes TOSCA YAML template or TOSCA Cloud Service Archive (CSAR)
+file as an input, with optional input of dictionary of needed parameters with their
+values, and produces in-memory objects of different TOSCA elements with their
+relationship to each other. It also creates a graph of TOSCA node templates and their
+relationship.
+
+The ToscaTemplate class located in the toscaparser/tosca_template.py is an entry
+class of the parser and various functionality of parser can be used by initiating
+this class. In order to see an example usage of TOSCA Parser from a separate tool,
+refer to the OpenStack heat-translator class TranslateTemplate located in the
+translator/osc/v1/translate.py module. The toscaparser/shell.py module of tosca-parser
+also provides a good reference on how to invoke TOSCA Parser from Command Line Interface.
+
+The toscaparser/elements sub-directory contains various modules to handle
+various TOSCA type elements like node type, relationship type etc. The
+entity_type.py module is a parent of all type elements. The toscaparser
+directory contains various python module to handle service template including
+topology template, node templates, relationship templates etc. The
+entity_template.py is a parent of all template elements.
+
+
+How To Use
+----------
+Please refer to `doc/source/usage.rst <https://github.com/openstack/tosca-parser/blob/master/doc/source/usage.rst>`_
+
+Project Info
+------------
+
+* License: Apache License, Version 2.0
+* Source: http://git.openstack.org/cgit/openstack/tosca-parser/
+
diff --git a/tosca2heat/tosca-parser/setup.cfg b/tosca2heat/tosca-parser/setup.cfg
index 77e1b2e..45a5ae7 100644
--- a/tosca2heat/tosca-parser/setup.cfg
+++ b/tosca2heat/tosca-parser/setup.cfg
@@ -3,7 +3,7 @@ name = tosca-parser
 url = https://launchpad.net/tosca-parser
 summary = Parser for TOSCA Simple Profile in YAML.
 description-file =
-    README.rst
+    README.md
 author = OpenStack
 author-email = openstack-dev@lists.openstack.org
 home-page = http://docs.openstack.org/developer/tosca-parser/
@@ -28,14 +28,6 @@ packages =
 console_scripts =
     tosca-parser = toscaparser.shell:main
 
-[build_sphinx]
-source-dir = doc/source
-build-dir = doc/build
-all_files = 1
-
-[upload_sphinx]
-upload-dir = doc/build/html
-
 [compile_catalog]
 directory = toscaparser/locale
 domain = toscaparser