Plan for improving xOpera's documentation

[anzoman]

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).

[anzoman]

The update plan for opera docs currently includes the following activities:

• add more examples and their description (AWS, Azure, GCP, OpenFaaS, Docker, Kubernetes etc.), the new TOSCA templates that will be described in the docs could reside in the almost forgotten opera-examples GitHub repository which was designed to be the central point for all the opera examples. And because opera might extend in the future, a lot of examples are to come and their maintenance and CI testing would be easier within a separated repo (the connected issue from some time ago is here: Move opera examples to integration test folder xopera-opera#93). So the necessary thing to do would feature moving all (RADON and SODALITE) examples to opera-examples repository and then we would need to establish some CI testing for them and later reference and describe them in docs.
• describe new opera commands and their usage targeting opera update and opera diff.
• describe the new tab completion feature - opera now has the ability to print out the shell completion script for the desired shell (currently we support bash and zsh) and since tab completion can be a helpful feature we should add a section where we describe how to set everything up properly.
• add a section about the proper preparation of TOSCA CSARs - a valid TOSCA CSAR needs to be prepared according to the standard and we should describe this process so that the user will be able to prepare and deploy TOSCA CSAR with opera. Here we can also mention opera package and opera unpackage CLI commands that can facilitate the packaging and unpackaging of the TOSCA CSARs.
• add info about TOSCA support describe TOSCA version support, list the supported TOSCA entities and those that are yet to be supported in the future, this can be done with checkboxes or within a table.
• make documentation downloadable which would bring some benefits for exporting docs as a pdf or other formats.
• add a contribution guide for opera which would describe what the user has to do to contribute to xOpera's project (some info about code style, commit messages and so on).
• document python code and use docstrings in documentation - python docstrings can be added to all functions and methods within opera's source code and then we can include them to our Sphinx documentation.
• add GitHub changelog - would be beneficial for the users who want to see the info about the latest releases and code changes.
• update sidebar by tools - the sidebar in xOpera's documentation could have multiple Sphinx toctrees for each tool which would make searching and going through documentation easier.
• add documentation for other xOpera tools - since xOpera's documentation could document all the tools that are connected to xOpera project we can have all docs moved here. Perhaps we can start with Template library.

@cankarm, @sstanovnik, @dradX if you have any other suggestions for the documentation updates we can add them to the wishlist above.