Documentation¶

This document holds instructions on writing the documentation.

Guidelines¶

We follow the following guidelines when writing documentation.

• start a document with "This document holds ..."
• use "we" instead of "you" or imperative
• use "Next, we" instead of "Then, we ...", "We then ...", etc.
• use ", see" instead of "..., as given in ...", "..., as presented in ...", etc.
• use the step-by-step guide template in docs/templates/guide
• use the specification template in docs/templates/specification
• use "as follows" instead of "in the following"

MkDocs¶

We use Material for MkDocs as documentation system. The files are located in the docs directory. Custom macros are implemented in docs/macros.py using mkdocs-macros.

First, install all dependencies. This will install several apt packages on the system and mkdocs in a virtual environment.

1

./task docs:install

Next, reload your session.

Next, start a local development server on http://localhost:8000.

1

./task docs:serve

Next, open the docs in your browser.

1

./task docs:open

Autogenerated Markdown¶

Some Markdown files are autogenerated, e.g., Dependencies or Interface. Changes must be made in the respective template files. Files are generated during the Release workflow and overwrite committed files. To warn the developer, include the following custom marco at the top of the template.

1

{{ autogenerated_notice('./task docs:generate:dependencies') }}

This will render the following warning, if the docs are served using ./task docs:serve but not when built.

Casts¶

The docs contain recorded demos. We use the following tools.

• asciinema to record a terminal session.
• demo-magic to automate the terminal session.
• asciinema-player to embed casts in a standalone manner.

Casts are not recorded during any workflow. The following command can be used to record the home cast for the landing page.

1

./task docs:record:home

A cast can be embedded using the custom macro asciinema_player inside a Markdown file.

1

{{ asciinema_player('getting-started') }}

This will embed the cast docs/docs/assets/casts/getting-started.cast inside the page as follows.

Export¶

To export registered pages as PDF, run the following command. The PDFs are stored in dist-docs.

1

./task docs:export

By default, https://vintner.opentosca.org is used. To export pages of http://localhost:8000, run the following command.

1

./task docs:export:local

Interface¶

To generate the documentation for the CLI and REST API, run the following command. This command is also executed during the Release workflow and overwrites committed files.

1

./task docs:generate:interface

Dependencies¶

To generate a list of licenses for all (transitive) dependencies, run the following command This command is also executed during the Release workflow and overwrites committed files.

1

./task docs:generate:dependencies

The list includes information, such as package name, version, license, etc., and is written to a CSV file. At the same time, the Dependencies page is generated.

Puccini¶

We use puccini to validate a service template. Therefore, run the following command.

1

./task puccini:check:single path/to/service-template.yaml

To validate all registered service templates, run the following command.

1

./task puccini:check

PlantUML¶

We use PlantUML for visualizing UML diagrams. Read PlantUML Guide for modeling instructions.

The following command generates PlantUML files for registered service templates. This command is also executed during the Release workflow and overwrites committed files. Furthermore, mkdocs_build_plantuml is used to plot PlantUML to SVGs when building the documentation.

1

./task docs:generate:puml

Note, we use the public PlantUML server https://www.plantuml.com/plantuml for plotting SVGs. It is also possible to start a local PlantUML server using Docker. Therefore, run the following command.

1

./task puml:up 

However, you also need to configure the following environment variables in docs/.env.

1
2

MKDOCS_PUML_SERVER=http://localhost:8080
MKDOCS_PUML_SERVER_SSL=true

To stop the local PlantUML server, run the following command.

1

./task puml:down

Queries4TOSCA¶

To generate the conformance tests for Queries4TOSCA, run the following command. This command is also executed during the Release workflow and overwrites committed files.

1

./task docs:generate:query

TOSCA SofDCar Profile¶

To generate the TOSCA SofDCar Profile, run the following command. This command is also executed during the Release workflow and overwrites committed files.

1

./task docs:generate:query

Variability4TOSCA¶

To generate the conformance tests for Variability4TOSCA, run the following command. This command is also executed during the Release workflow and overwrites committed files.

1

./task docs:generate:query

Limitations¶

• Performance is suffering due to the heavy use of plugins.
• It is not possible to configure which release should be shown in the navigation bar. The latest release is always use which is in general correct.