Repository: incubator-ariatosca Updated Branches: refs/heads/packaging 653e1e940 -> 72beb4350
readme conversion test Project: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/commit/72beb435 Tree: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/tree/72beb435 Diff: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/diff/72beb435 Branch: refs/heads/packaging Commit: 72beb43500b4d0d92117762a552147ef550f4adf Parents: 653e1e9 Author: Ran Ziv <[email protected]> Authored: Mon Jun 5 11:55:48 2017 +0300 Committer: Ran Ziv <[email protected]> Committed: Mon Jun 5 11:55:48 2017 +0300 ---------------------------------------------------------------------- README.rst | 294 ++++++++++++++++++++++++++++++++------------------------ 1 file changed, 166 insertions(+), 128 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/72beb435/README.rst ---------------------------------------------------------------------- diff --git a/README.rst b/README.rst index 2fa21a5..073fe6c 100644 --- a/README.rst +++ b/README.rst @@ -1,58 +1,120 @@ ARIA ==== -| |Build Status| -| |Appveyor Build Status| -| |License| +|Build Status| |Appveyor Build Status| |License| -| `ARIA`_ is a minimal TOSCA orchestrator, as well as a platform for - building -| TOSCA-based products. Its features can be accessed via a - well-documented Python API. +`ARIA <http://ariatosca.org/>`__ is a minimal TOSCA orchestrator, as +well as a platform for building TOSCA-based products. Its features can +be accessed via a well-documented Python API. -| On its own, ARIA provides built-in tools for blueprint validation and - for creating ready-to-run -| service instances. +On its own, ARIA provides built-in tools for blueprint validation and +for creating ready-to-run service instances. -| ARIA adheres strictly and meticulously to the -| `TOSCA Simple Profile v1.0 cos01 specification`_, -| providing state-of-the-art validation at seven different levels: +ARIA adheres strictly and meticulously to the `TOSCA Simple Profile v1.0 +cos01 +specification <http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.0/cos01/TOSCA-Simple-Profile-YAML-v1.0-cos01.html>`__, +providing state-of-the-art validation at seven different levels: .. raw:: html <ol start="0"> - <li>Platform errors. E.g. network, hardware, or even an internal bug in ARIA (let us know, - please!).</li> - <li>Syntax and format errors. E.g. non-compliant YAML, XML, JSON.</li> - <li>Field validation. E.g. assigning a string where an integer is expected, using a list instead of - a dict.</li> - <li>Relationships between fields within a type. This is "grammar" as it applies to rules for - setting the values of fields in relation to each other.</li> - <li>Relationships between types. E.g. referring to an unknown type, causing a type inheritance - loop.</li> - <li>Topology. These errors happen if requirements and capabilities cannot be matched in order to - assemble a valid topology.</li> - <li>External dependencies. These errors happen if requirement/capability matching fails due to - external resources missing, e.g. the lack of a valid virtual machine, API credentials, etc. - </li> + +.. raw:: html + + <li> + +Platform errors. E.g. network, hardware, or even an internal bug in ARIA +(let us know, please!). + +.. raw:: html + + </li> + +.. raw:: html + + <li> + +Syntax and format errors. E.g. non-compliant YAML, XML, JSON. + +.. raw:: html + + </li> + +.. raw:: html + + <li> + +Field validation. E.g. assigning a string where an integer is expected, +using a list instead of a dict. + +.. raw:: html + + </li> + +.. raw:: html + + <li> + +Relationships between fields within a type. This is "grammar" as it +applies to rules for setting the values of fields in relation to each +other. + +.. raw:: html + + </li> + +.. raw:: html + + <li> + +Relationships between types. E.g. referring to an unknown type, causing +a type inheritance loop. + +.. raw:: html + + </li> + +.. raw:: html + + <li> + +Topology. These errors happen if requirements and capabilities cannot be +matched in order to assemble a valid topology. + +.. raw:: html + + </li> + +.. raw:: html + + <li> + +External dependencies. These errors happen if requirement/capability +matching fails due to external resources missing, e.g. the lack of a +valid virtual machine, API credentials, etc. + +.. raw:: html + + </li> + +.. raw:: html + </ol> -| Validation errors include a plain English message and when relevant - the exact location (file, row, -| column) of the data the caused the error. +Validation errors include a plain English message and when relevant the +exact location (file, row, column) of the data the caused the error. -| The ARIA API documentation always links to the relevant section of the - specification, and likewise -| we provide an annotated version of the specification that links back - to the API documentation. +The ARIA API documentation always links to the relevant section of the +specification, and likewise we provide an annotated version of the +specification that links back to the API documentation. Quick Start ----------- You need Python 2.6 or 2.7. Python 3+ is not currently supported. -| To install, we recommend using `pip`_ and a -| `virtualenv`_. +To install, we recommend using `pip <https://pip.pypa.io/>`__ and a +`virtualenv <https://virtualenv.pypa.io/en/stable/>`__. In Debian-based systems: @@ -78,19 +140,7 @@ To install the latest development snapshot of ARIA: . env/bin/activate pip install git+http://git-wip-us.apache.org/repos/asf/incubator-ariatosca.git -.. _ARIA: http://ariatosca.org/ -.. _TOSCA Simple Profile v1.0 cos01 specification: http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.0/cos01/TOSCA-Simple-Profile-YAML-v1.0-cos01.html -.. _pip: https://pip.pypa.io/ -.. _virtualenv: https://virtualenv.pypa.io/en/stable/ - -.. |Build Status| image:: https://travis-ci.org/apache/incubator-ariatosca.svg?branch=master - :target: https://travis-ci.org/apache/incubator-ariatosca -.. |Appveyor Build Status| image:: https://ci.appveyor.com/api/projects/status/ltv89jk63ahiu306?svg=true - :target: https://ci.appveyor.com/project/ApacheSoftwareFoundation/incubator-ariatosca/history -.. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg - :target: https://opensource.org/licenses/Apache-2.0 - -To test it, letâs create a service instance from a TOSCA blueprint: +To test it, let's create a service instance from a TOSCA blueprint: :: @@ -115,9 +165,9 @@ the blueprint aria parse blueprints/tosca/node-cellar/node-cellar.yaml --inputs='{"openstack_credential": {"user": "username"}}' -| Instead of providing them explicitly, you can also provide them in a - file or URL, in either JSON or -| YAML. If you do so, the value must end in â.jsonâ or â.yamlâ: +Instead of providing them explicitly, you can also provide them in a +file or URL, in either JSON or YAML. If you do so, the value must end in +".json" or ".yaml": :: @@ -126,48 +176,41 @@ the blueprint CLI --- -| Though ARIA is fully exposed as an API, it also comes with a CLI tool - to allow you to work from the -| shell: +Though ARIA is fully exposed as an API, it also comes with a CLI tool to +allow you to work from the shell: :: aria parse blueprints/tosca/node-cellar/node-cellar.yaml instance -| The ``parse`` command supports the following directives to create - variations of the default consumer -| chain: +The ``parse`` command supports the following directives to create +variations of the default consumer chain: - ``presentation``: emits a colorized textual representation of the - Python presentation classes - wrapping the blueprint. + Python presentation classes wrapping the blueprint. - ``model``: emits a colorized textual representation of the complete - service model derived from the - validated blueprint. This includes all the node templates, with their - requirements satisfied at - the level of relating to other node templates. + service model derived from the validated blueprint. This includes all + the node templates, with their requirements satisfied at the level of + relating to other node templates. - ``types``: emits a colorized textual representation of the type hierarchies. - ``instance``: **this is the default command**; emits a colorized - textual representation of a - service instance instantiated from the service model. Here the node - templates are each used to - create one or more nodes, with the appropriate relationships between - them. Note that every time - you run this consumer, you will get a different set of node IDs. Use - ``--graph`` to see just the - node relationship graph. + textual representation of a service instance instantiated from the + service model. Here the node templates are each used to create one or + more nodes, with the appropriate relationships between them. Note + that every time you run this consumer, you will get a different set + of node IDs. Use ``--graph`` to see just the node relationship graph. For all these commands, you can also use ``--json`` or ``--yaml`` flags to emit in those formats. -| Additionally, The CLI tool lets you specify the complete classname of - your own custom consumer to -| chain at the end of the default consumer chain, after ``instance``. +Additionally, The CLI tool lets you specify the complete classname of +your own custom consumer to chain at the end of the default consumer +chain, after ``instance``. -| Your custom consumer can be an entry point into a powerful TOSCA-based - tool or application, such as -| an orchestrator, a graphical modeling tool, etc. +Your custom consumer can be an entry point into a powerful TOSCA-based +tool or application, such as an orchestrator, a graphical modeling tool, +etc. Development ----------- @@ -191,7 +234,7 @@ To run tests: pip install tox tox -Hereâs a quick example of using the API to parse YAML text into a +Here's a quick example of using the API to parse YAML text into a service instance: :: @@ -222,60 +265,55 @@ service instance: Parser API Architecture ----------------------- -| ARIAâs parsing engine comprises individual âconsumersâ (in the - ``aria.parser.consumption`` package) -| that do things with blueprints. When chained together, each performs a - different task, adds its own -| validations, and can provide its own output. +ARIA's parsing engine comprises individual "consumers" (in the +``aria.parser.consumption`` package) that do things with blueprints. +When chained together, each performs a different task, adds its own +validations, and can provide its own output. Parsing happens in five phases, represented in five packages: - ``aria.parser.loading``: Loaders are used to read the TOSCA data, - usually as text. For example - UriTextLoader will load text from URIs (including files). + usually as text. For example UriTextLoader will load text from URIs + (including files). - ``aria.parser.reading``: Readers convert data from the loaders into - agnostic raw data. For - example, ``YamlReader`` converts YAML text into Python dicts, lists, - and primitives. + agnostic raw data. For example, ``YamlReader`` converts YAML text + into Python dicts, lists, and primitives. - ``aria.parser.presentation``: Presenters wrap the agnostic raw data - in a nice - Python facade (a âpresentationâ) that makes it much easier to work - with the data, including - utilities for validation, querying, etc. Note that presenters are - *wrappers*: the agnostic raw - data is always maintained intact, and can always be accessed directly - or written back to files. + in a nice Python facade (a "presentation") that makes it much easier + to work with the data, including utilities for validation, querying, + etc. Note that presenters are *wrappers*: the agnostic raw data is + always maintained intact, and can always be accessed directly or + written back to files. - ``aria.parser.modeling.model``: Here the topology is normalized into - a coherent structure of - node templates, requirements, and capabilities. Types are inherited - and properties are assigned. - The service model is a *new* structure, which is not mapped to the - YAML. In fact, it is possible - to generate the model programmatically, or from a DSL parser other - than TOSCA. + a coherent structure of node templates, requirements, and + capabilities. Types are inherited and properties are assigned. The + service model is a *new* structure, which is not mapped to the YAML. + In fact, it is possible to generate the model programmatically, or + from a DSL parser other than TOSCA. - ``aria.parser.modeling.instance``: The service instance is an - instantiated service model. Node - templates turn into node instances (with unique IDs), and - requirements are satisfied by matching - them to capabilities. This is where level 5 validation errors are - detected (see above). - -| The phases do not have to be used in order. Indeed, consumers do not - have to be used at all: ARIA -| can be used to *produce* blueprints. For example, it is possible to - fill in the -| ``aria.parser.presentation`` classes programmatically, in Python, and - then write the presentation -| to a YAML file as compliant TOSCA. The same technique can be used to - convert from one DSL (consume -| it) to another (write it). - -| The term âagnostic raw dataâ (ARD?) appears often in the - documentation. It denotes data structures -| comprising *only* Python dicts, lists, and primitives, such that they - can always be converted to and -| from language-agnostic formats such as YAML, JSON, and XML. A - considerable effort has been made to -| conserve the agnostic raw data at all times. Thus, though ARIA makes - good use of the dynamic power -| of Python, you will *always* be able to use ARIA with other systems. \ No newline at end of file + instantiated service model. Node templates turn into node instances + (with unique IDs), and requirements are satisfied by matching them to + capabilities. This is where level 5 validation errors are detected + (see above). + +The phases do not have to be used in order. Indeed, consumers do not +have to be used at all: ARIA can be used to *produce* blueprints. For +example, it is possible to fill in the ``aria.parser.presentation`` +classes programmatically, in Python, and then write the presentation to +a YAML file as compliant TOSCA. The same technique can be used to +convert from one DSL (consume it) to another (write it). + +The term "agnostic raw data" (ARD?) appears often in the documentation. +It denotes data structures comprising *only* Python dicts, lists, and +primitives, such that they can always be converted to and from +language-agnostic formats such as YAML, JSON, and XML. A considerable +effort has been made to conserve the agnostic raw data at all times. +Thus, though ARIA makes good use of the dynamic power of Python, you +will *always* be able to use ARIA with other systems. + +.. |Build Status| image:: https://travis-ci.org/apache/incubator-ariatosca.svg?branch=master + :target: https://travis-ci.org/apache/incubator-ariatosca +.. |Appveyor Build Status| image:: https://ci.appveyor.com/api/projects/status/ltv89jk63ahiu306?svg=true + :target: https://ci.appveyor.com/project/ApacheSoftwareFoundation/incubator-ariatosca/history +.. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg + :target: https://opensource.org/licenses/Apache-2.0 \ No newline at end of file
