Documenting examples with visual diagrams

[philippemerle]

I propose to improve the documentation (README.md) of each xOpera example by adding visual diagrams representing the example topology and all defined types.

Following are diagram examples that could be added in order to document examples.

[anzoman]

@philippemerle good idea, this would help the users to understand the example better. Are the diagrams you posted exported with your TOSCA inspection tool?

[philippemerle]

Yes these diagrams are automatically generated from original xOpera service templates.

[cankarm]

@philippemerle thank you for your contributions to the xOpera project. I noticed and tried your TOSCA inspection tool a few days ago and I'm impressed about the ease of visualizing the TOSCA content. We will definitely discuss how we could improve the way of describing each example with adding the proposed visual diagrams. Similarly, we could do something similar for services published in TPS.

[philippemerle]

The PR #50 contains most of all diagrams generated with our Cloudnet TOSCA toolbox. I will let you modify each example's README.md file to add the appropriate Markup links to the diagrams you consider the best documenting each example.

Let's note that it is possible to generate colored UML2 component and deployment diagrams including graphical icons too. See https://github.com/philippemerle/TORCH/blob/master/examples/Cloudnet_TOSCA_Toolbox_Results/Uml2Diagrams/csar_sockshop_dep.zip/tosca_sockshop-uml2-deployment-diagram.png as example. Just give me what colors and icons you want to associate to each TOSCA node type.

[anzoman]

Hi @philippemerle, thanks a lot for generating diagrams for all our examples in #50. They look great and can be really useful to see what the example does.

Although diagrams are nice to have I see them as an extra feature for the users that want to explore deeper, so I would not put them directly into this repository because the examples will probably get changed over time and this would mean that we have to generate new images and upload them again. I'd rather see that we create a manual GitHub Actions workflow that would allow us generating these diagrams whenever we need them. The action could be triggered manually and we would get back the diagram for every example (or even better if you need a diagram for just one example you could place this as an input to the GH Action). So, I would suggest that we keep just the necessary files for generating the diagrams (we should put them in a hidden .cloudnet-tosca-toolbox folder so that they would not be mistaken for examples) and use them in the new GH Action. This would still mean that every user can clone the directory and generate those diagrams locally for himself. The other option would be keeping the diagrams within this repository and generating new ones on every push action to replace the old ones, but this doesn't sound so good as we would generate and replace a lot of files every time.

What do you think @cankarm?

[abitrolly]

The other option would be keeping the diagrams within this repository and generating new ones on every push action to replace the old ones, but this doesn't sound so good as we would generate and replace a lot of files every time.

If the builds are reproducible, there will be only diffs for actual changes.

It is also not clear how to get diagrams that visually match those used in TOSCA standard.

[philippemerle]

It is also not clear how to get diagrams that visually match those used in TOSCA standard.

Diagrams generated with Cloudnet TOSCA toolbox are conform to the UML2 standard.
Diagrams used in TOSCA standard are informal ones conform to no diagram standard.

[abitrolly]

They conform to TOSCA standard, which may not map to the UML2. My concern was mainly about the design, but if these diagrams are not semantically equivalent, I doubt it is a good idea to accompany official examples with them (but not a bad idea either).