xlab-si / xopera-docs Goto Github PK

Description

The opera's documentation is currently available on GitHub pages here: https://xlab-si.github.io/xopera-docs/.

If one looks at the documentation at the moment, he can get info on how to download and run opera TOSCA orchestrator, where opera is/has been used (EU projects), what is the purpose of the tool, past contributors, opera SaaS documentation and so on. This is all very nice but things can get better. I would recommend splitting our documentation into sensible sections where the user would find other information like:

• how every opera command is used exactly and troubleshooting
• which parts of TOSCA does opera support and which are yet to be implemented
• which automation tools are supported and how
• some simple and complex examples based on supported TOSCA entities
• how can users contribute to opera

This last line is very important for the newcomers and users that would want to help and contribute to opera. Since opera's source code can be complex to understand some times, we would need to have some kind of a roadmap that would lead programmers through the different parts of the code. I would also recommend that we modify README and and add a link to the docs there.

I believe that all this can and will make opera a lot more attractive to the new users.

Steps

We will need to modify rst files that are located in /docs folder.

Current behaviour

Opera has a documentation but it is far from being complete.

Expected results

To have a more user friendly and informative documentation.

Note

This issue was moved here from xlab-si/xopera-opera#121 because we moved all xOpera's docs bach to this repo (see #2).

https://xlab-si.github.io/xopera-docs/cli.html#quickstart is awesome. Unfortunately, it ends with no links to expand details what didn't fit into the intro.

Like how to set an output variable from a playbook. Had to go through all files to find that this is done through standard set_stats Ansible module.

• https://github.com/xlab-si/xopera-examples/blob/e2b7a58067ee9ad283af3d933aaa793c3360387c/tosca/outputs/playbooks/create.yaml
• https://github.com/xlab-si/xopera-examples/blob/e2b7a58067ee9ad283af3d933aaa793c3360387c/tosca/outputs/service.yaml

It would be nice to see more tutorials that gradually introduce TOSCA concepts for Ansible users and how do they play together. What immediately comes in mind.

• Showing user level messages during deployment
• Setting output variables from a playbook
• Reading new parameter values as a result of deployment and passing then between nodes
• Setting different SSH access parameters for different nodes in the same deployment

Hello,

I was reading through the docs and identified some typos/ issues.
I am referring to https://github.com/xlab-si/xopera-docs/blob/790f7f2f177085897572fe5adde9d756a3c91fa0/docs/cli.rst in the following.

• "CLI commands references": "purpose and description" of "opera package" is wrong
• "CLI commands references": "purpose and description" of "opera unpackage" is wrong
• "CLI commands references": the text at the end has a problem: "The commands can be executed in a random order and the orchestrator will warn and the orchestrator will warn you in case if any problems. Each CLI command is described more in detail in the following sections."
• "opera deploy" description: "case" should be "care" in "If the number of specified workers is higher than the number of independent nodes, the orchestrator will take care of this and will decrease the amount of workers if needed."
• "opera info": missing a word in "print the outputs of the deploy/undeploy application."
• "opera info" description: "This includes printing out the path to TOSCA service template"
• "opera info" description: code block of json example has some problems since the text starting with "xOpera TOSCA orchestration tool is still inside the code box

And a minor one:

• The service template of the CLI Quickstart has some minor differences to the example files. Different default value for content, metadata and content input has been renamend to marker.

Greetings 😄

Description

This repository was first mentioned to be a central point for the xOpera's documentation that would contain the user's manual. Initially the documentation was created here and was served on GitHub pages at https://xlab-si.github.io/xopera-docs/. After some time we moved it to xopera-opera repository because at that time the documentation was targeting only the core parser and opera CLI. However, we also wanted to explain the whole xOpera ecosystem and all the connected tools so we realized that in this case the documentation does not fit in xopera-opera anymore and has to be either organized in every repository separately or moved back here. We decided for the latter option because maintaining documentation for different tools would be difficult. Moving the documentation here would also free xopera-opera repository because we wouldn't have to build docs there anymore and we could focus only on the orchestrator there and also the CI/CD will be faster.

Steps

We will need to delete all docs from xopera-opera here and move them here.

Current behaviour

The opera's docs are currently available on GitHub pages here: https://xlab-si.github.io/xopera-opera/.

Expected results

To have all documentation again in this repository.

Note

cc @cankarm, @sstanovnik