{% extends 'base.html' %} {% block title %}How to document jobs and roles for Zubbi{% endblock %} {% block header %}

How to document jobs and roles for Zubbi

{% endblock %} {% block content %}

Supported formats

For the best result, we recommend to write the documentation of your jobs and roles in reStructuredText (.rst) format. As a fallback, Zubbi also supports Markdown (.md) and Text (.txt) files.

Where to put the documentation?

For jobs, the documentation must be put in the description field of the job definition. In this case, only reStructuredText format is supported.

In case of roles, the documentation must be put in a README file inside the role's directory. Please note, that the file extension must match the used format to be rendered properly.

Documenting with reStructuredText

For a short overview on reStructuredText, you can take a look at the quickref and the Cheat Sheet.

We are using the zuul-sphinx plugin for parsing the documentation files. This Sphinx extension provides some additional directives that can be used within the job and role documentation.

{% block additional_links %}{% endblock %}

Role example

{% include 'includes/role-example.html' %}
Job example
{% include 'includes/job-example.html' %}

Showing code examples

Sphinx uses pygments to allow syntax highlighting in code examples. To activate syntax highlighting in your job or role description, you have to use the code-block directive for code examples like this:

{% include 'includes/code-example.html' %}

Be sure to provide the correct language in the code-block directive, otherwise it won't be highlighted properly. For more information you can take a look at the official Sphinx documentation.

Changelogs

If you define a CHANGELOG file inside a role's directory, Zubbi will show its contents in the changelog tab of a role's details page. This file is rendered the same way like the README file, so the same rules apply. Our recommended changelog format is the following (CHANGELOG.rst):

{% include 'includes/changelog-example.html' %}
{% endblock %}