Skip to content

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

Warning

This only works on Linux.

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.

Warning

Do not edit! This file is autogenerated using ./task docs:generate:dependencies and will be overwritten during the Release workflow! (This warning is not shown once deployed)

Casts

Warning

This only works on Linux.

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

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

Warning

This only works on Linux.

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

Warning

This only works on Linux.

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. We use mkdocs_build_plantuml to plot PlantUML to SVGs when building the documentation. Note, we use the public PlantUML server https://www.plantuml.com/plantuml for plotting SVGs.

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.
Last update: December 13, 2024