{% extends 'base.html' %} {% block title %}How to document jobs and roles for Zubbi{% endblock %} {% block header %}
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.
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.
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 %}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.
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' %}