From 6fecb729f550f4f543739375df8148ab9de38668 Mon Sep 17 00:00:00 2001 From: shangxdy Date: Thu, 18 Aug 2016 21:14:39 +0800 Subject: Update the documents in Release C As a developer; I want anybody who cares of project of parser to know what new features in release C; So i update the distribution documents. JIRA:PRASER-87 Change-Id: I0537ba55fa12daa2975f1b794908bca457cfd9c2 Signed-off-by: shangxdy --- docs/configguide/featureconfig.rst | 18 ++----- docs/configguide/index.rst | 15 ++++++ docs/configguide/installerconfig.rst | 12 +++-- docs/configguide/postinstall.rst | 30 ----------- docs/userguide/featureusage.rst | 96 +++++++++++++++++++++++++++++++++--- docs/userguide/index.rst | 26 ++++++++++ docs/userguide/testusage.rst | 54 +++++++++++++++++--- 7 files changed, 191 insertions(+), 60 deletions(-) create mode 100644 docs/configguide/index.rst delete mode 100644 docs/configguide/postinstall.rst create mode 100644 docs/userguide/index.rst (limited to 'docs') diff --git a/docs/configguide/featureconfig.rst b/docs/configguide/featureconfig.rst index 188ee55..dc4fc50 100644 --- a/docs/configguide/featureconfig.rst +++ b/docs/configguide/featureconfig.rst @@ -4,25 +4,17 @@ Parser configuration ===================== -Add a brief introduction to configure OPNFV with this specific feature including -dependancies on platform components, this description should be at a level that -will apply to any installer providing the pre-requisite components. +Parser can be configured with any installer in current OPNFV, it only depends on +openstack. Pre-configuration activities ---------------------------- -Describe specific pre-configuration activities. This should include ensuring the -right components are installed by the installation tools as required for your -feature to function. Refer to the previous installer configuration chapters, -installations guide and release notes +For parser, there is not specific pre-configuration activities. Hardware configuration ---------------------- -Describe the hardware configuration needed for this specific feature +For parser, there is not hardware configuration needed for any current feature. Feature configuration --------------------- -Describe the procedures to configure your feature on the platform in order -that it is ready to use according to the feature instructions in the platform -user guide. Where applicable you should add content in the postinstall.rst -to validate the feature is configured for use. -(checking components are installed correctly etc...) +For parser, there is not specific configure on openstack. diff --git a/docs/configguide/index.rst b/docs/configguide/index.rst new file mode 100644 index 0000000..03ba4b0 --- /dev/null +++ b/docs/configguide/index.rst @@ -0,0 +1,15 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International +.. License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) OPNFV, Ericsson AB and others. + +========================== +Parser Configuration Guide +========================== + +.. toctree:: + :numbered: + :maxdepth: 2 + +.. include:: featureconfig.rst +.. include:: installerconfig.rst diff --git a/docs/configguide/installerconfig.rst b/docs/configguide/installerconfig.rst index ddc7bea..efe6265 100644 --- a/docs/configguide/installerconfig.rst +++ b/docs/configguide/installerconfig.rst @@ -4,23 +4,25 @@ Parser configuration ===================== -Add a brief introduction to configure OPNFV with this specific installer +Parser can be configured with any installer in current OPNFV. Pre-configuration activities ----------------------------- -Describe specific pre-configuration activities. Refer to Installations guide and release notes +For parser, there is not specific pre-configuration activities. Hardware configuration ----------------------- -Describe the hardware configuration needed for this specific installer +For parser, there is not hardware configuration needed for this specific installer. Jumphost configuration ----------------------- -Describe intial Jumphost configuration (network and software)needed in order to deploy the installer +For parser, there is not intial Jumphost configuration (network and software)needed in order +to deploy any installer. Platform components configuration --------------------------------- -Describe the configuration of each component in the installer +For tosca2heat components(tosca-parser and heat-translator) in parser,there are not specific +configuration of each component in installer. diff --git a/docs/configguide/postinstall.rst b/docs/configguide/postinstall.rst deleted file mode 100644 index 252bff6..0000000 --- a/docs/configguide/postinstall.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 -.. (c) - -Parser post installation procedures -==================================== -Add a brief introduction to the methods of validating the installation -according to this specific installer or feature. - -Automated post installation activities ---------------------------------------- -Describe specific post installation activities performed by the OPNFV -deployment pipeline including testing activities and reports. Refer to -the relevant testing guides, results, and release notes. - -note: this section should be singular and derived from the test projects -once we have one test suite to run for all deploy tools. This is not the -case yet so each deploy tool will need to provide (hopefully very simillar) -documentation of this. - -Parser post configuration procedures -------------------------------------- -Describe any deploy tool or feature specific scripts, tests or procedures -that should be carried out on the deployment post install and configuration -in this section. - -Platform components validation -------------------------------- -Describe any component specific validation procedures necessary for your -deployment tool in this section. diff --git a/docs/userguide/featureusage.rst b/docs/userguide/featureusage.rst index f133134..db2557f 100644 --- a/docs/userguide/featureusage.rst +++ b/docs/userguide/featureusage.rst @@ -2,11 +2,95 @@ .. http://creativecommons.org/licenses/by/4.0 .. (c) - capabilities and usage -================================ -Describe the specific capabilities and usage for feature. +Installation +============================ - ------------------------------------------------ -Describe with examples how to use specfic features. +Please follow the below installation steps to install parser. +Step 1: Clone the parser project. + +.. code-block:: bash + + git clone https://gerrit.opnfv.org/gerrit/parser + +Step 2: Install the heat-translator sub project. + +.. code-block:: bash + + # uninstall pre-installed tosca-parser + pip uninstall -y heat-translator + + # change directory to heat-translator + cd parser/tosca2heat/heat-translator + + # install requirements + pip install -r requirements.txt + + # install heat-translator + python setup.py install + +Step 3: Install the tosca-parser sub project. + +.. code-block:: bash + + # uninstall pre-installed tosca-parser + pip uninstall -y tosca-parser + + # change directory to tosca-parser + cd parser/tosca2heat/tosca-parser + + # install requirements + pip install -r requirements.txt + + # install tosca-parser + python setup.py install + + + **Notes** It must uninstall pre-installed tosca-parser and heat-translator before install the two + components, and install heat-translator before installing tosca-parser, which is sure to use the + OPNFV version of tosca-parser and heat-translator other than openstack's components. + +Execution +=========================== + +Step 1: Change directory to where the tosca yaml files are present, example is +below with vRNC definiton. + +.. code-block:: bash + + cd parser/tosca2heat/tosca-parser/toscaparser/extensions/nfv/tests/data/vRNC/Definitions + + +Step 2: Run the python command heat-translator with the TOSCA yaml file as an input option. + +.. code-block:: bash + + heat-translator --template-file= --template-type=tosca + --outpurt-file= + +Example: + +.. code-block:: bash + + heat-translator --template-file=vRNC.yaml \ + --template-type=tosca --output-file=vRNC_hot.yaml + +Notes: heat-translator will call class of ToscaTemplate in tosca-parser firstly to validate and parse input yaml file, +then tranlate the file into hot file, if you only want to validate or check the input file +and don't want to translate, please use tosaca-parser as following: + +.. code-block:: bash + + tosca-parser --template-file= + +Example: + +.. code-block:: bash + + tosca-parser --template-file=vRNC.yaml + +References +=========================== +Refer two upstream components: + https://github.com/openstack/tosca-parser/blob/master/doc/source/usage.rst + https://github.com/openstack/heat-translator/blob/master/doc/source/usage.rst diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst new file mode 100644 index 0000000..9174daa --- /dev/null +++ b/docs/userguide/index.rst @@ -0,0 +1,26 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International +.. License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) OPNFV, Ericsson AB and others. + +================= +Parser User Guide +================= +Parser is an open source project and licensed under Apache 2. Parser will help +to provide a tooling mechanism, by parsing Telecom operators VNF descriptors +(YANG templates) into TOSCA templates and then further translate TOSCA templates +into certain common templates, which could be used in IaaS orchestration projects +like OpenStack Heat(the template file is HOT, which stands for Heat Orchestrator +Template), this document is about simple TOSCA to HOT, and the example is a vRNC +(virtual Radio Network Controller) definition with format translated from simple +TOSCA(parser's input file format) to HOT(parser's output file format), which can +be deployed by heat directly. + +Contents: + +.. toctree:: + :numbered: + :maxdepth: 2 + +.. include:: featureusage.rst +.. include:: testusage.rst diff --git a/docs/userguide/testusage.rst b/docs/userguide/testusage.rst index 9f9bdc9..35dacae 100644 --- a/docs/userguide/testusage.rst +++ b/docs/userguide/testusage.rst @@ -2,11 +2,53 @@ .. http://creativecommons.org/licenses/by/4.0 .. (c) - capabilities and usage -================================ -Describe the specific capabilities and usage for testing. +Test use tox +=========================== +1. run tox in tosca-parser sub project - --------------------------------------- -Describe with examples how to use specfic test frameworks. +.. code-block:: bash + + # change directory to tosca-parser + cd parser/tosca2heat/tosca-parser + + # run with pep8 + tox -epep8 + + # run unit test + tox -epy27 + +or + +.. code-block:: bash + + # change directory to tosca-parser + cd parser/tosca2heat/tosca-parser + + # run tox + tox + + +2. run tox in heat-translator sub project + +.. code-block:: bash + + # change directory to heat-translator + cd parser/tosca2heat/heat-translator + + # run with pep8 + tox -epep8 + + # run unit test + tox -epy27 + tox -epy34 + +or + +.. code-block:: bash + + # change directory to heat-translator + cd parser/tosca2heat/heat-translator + + # run tox + tox -- cgit 1.2.3-korg