GenerateDocumentation#

Generate keyword documentation with the documentation template.

Enabling the transformer

GenerateDocumentation is not included in default transformers, that’s why you need to call it with --transform explicitly:

robotidy --transform GenerateDocumentation src

Or configure enabled parameter:

robotidy --configure GenerateDocumentation:enabled=True

By default, GenerateDocumentation uses Google docstring as the documentation template.

*** Keywords ***
Keyword
    [Arguments]    ${arg}
    ${var}   ${var2}    Step
    RETURN    ${var}    ${var2}

Keyword With ${embedded} Variable
    Step

*** Keywords ***
Keyword
    [Documentation]
    ...
    ...    Arguments:
    ...        ${arg}:
    ...
    ...    Returns:
    ...        ${var}
    ...        ${var2}
    [Arguments]    ${arg}
    ${var}   ${var2}    Step
    RETURN    ${var}    ${var2}

Keyword With ${embedded} Variable
    [Documentation]
    ...
    ...    Arguments:
    ...        ${embedded}:
    Step

Overwriting documentation#

The documentation will not be added if it is already present in the keyword. You can configure it by using overwrite parameter:

*** Keywords ***
Keyword With Documentation
    [Documentation]    Short description.
    [Arguments]    ${arg}
    Step

*** Keywords ***
Keyword With Documentation
    [Documentation]    Short description.
    [Arguments]    ${arg}
    Step

*** Keywords ***
Keyword With Documentation
    [Documentation]
    ...    Arguments:
    ...        ${arg}:
    [Arguments]    ${arg}
    Step

Custom template#

Custom templates can be loaded from the file using doc_template parameter. If you pass google string it will use default template:

> robotidy --configure GenerateDocumentation:doc_template=google src

Templates support Jinja templating engine and we are providing several variables based on the keyword data. Below, there is a default template:

{% if keyword.arguments|length > 0 %}
{{ formatting.cont_indent }}Args:
{%- for arg in keyword.arguments %}
{{ formatting.cont_indent }}{{ formatting.cont_indent }}{{ arg.name }}: {% endfor %}
{% endif -%}
{% if keyword.returns|length > 0 %}
{{ formatting.cont_indent }}Returns:
{%- for value in keyword.returns %}
{{ formatting.cont_indent }}{{ formatting.cont_indent }}{{ value }}: {% endfor %}
{% endif -%}

The Jinja syntax is described here. You can use it as a reference to create your own template. The following subsections explain in detail possible features.

Path to template can be absolute or relative (to working directory or configuration file directory):

> robotidy --configure GenerateDocumentation;doc_template="C:/doc_templates/template.jinja" src
> robotidy --configure GenerateDocumentation:doc_template="template.jinja" src

Note that to pass parameter value with : (like a absolute path), you need to use ; as a parameter separator.

First line of the documentation

The first line of the template is also the first line of the documentation that goes next to the [Documentation] setting.

  First line of template
  Second line of example
Third line.

*** Keywords ***
Keyword
    [Documentation]    First line of template
    ...    Second line of example
    ...  Third line.
    Step

Leave the first line empty in the template if you want to start documentation from the second line.

Whitespace can be static or dynamic

Any whitespace in the template will apply to the documentation. For example you can put 4 spaces after every argument and before -> sign:

Args:
{%- for arg in keyword.arguments %}
        {{ arg.name }}    ->{% endfor %}

*** Keywords ***
Keyword
    [Arguments]    ${arguments}    ${arg}    ${arg2}
    Step

*** Keywords ***
Keyword
    [Documentation]
    ...    Args:
    ...        ${arguments}    ->
    ...        ${arg}    ->
    ...        ${arg2}    ->
    [Arguments]    ${arguments}    ${arg}    ${arg2}
    Step

Robotidy provides also formatting class that contains two variables:

  • separator (default 4 spaces) - spacing between tokens

  • cont_indent (default 4 spaces) - spacing after ... signs

You can use them in the template - and their values will be affected by your configuration:

{{ formatting.separator }}
{{ formatting.cont_indent }}
Arguments data

Robotidy provides arguments as a list of variables in keyword.arguments variable. Every argument contains the following variables:

  • name - name of the argument without default value (ie. ${arg})

  • default - default value (ie. value)

  • full_name - name with default value (ie. ${arg} = value)

You can use them in the template:

Arguments:
{%- for arg in keyword.arguments %}
    {{ arg.name }} - {{ arg.default }}:{% endfor %}

*** Keywords ***
Keyword
    [Arguments]    ${var}    ${var2} = 2
    Step

*** Keywords ***
Keyword
    [Documentation]
    ...    Arguments:
    ...        ${var} - :
    ...        ${var2} - 2:
    [Arguments]    ${var}    ${var2} = 2
    Step

Note that you can use Jinja templating features like if blocks. For example, if you want to put = between the argument name and default value (only if default value is not empty), you can use:

{{ arg.name }}{% if arg.default %} = '{{ arg.default }}'{% endif %}
Returned values data

Returned values are provided as a list of variables names in keyword.returns variable.

Returns:
{%- for value in keyword.returns %}
    {{ value }}:{% endfor %}

*** Keywords ***
Keyword
    ${value}    Step
    RETURN    ${value}

*** Keywords ***
Keyword
    [Documentation]
    ...    Returns:
    ...        ${value}:
    ${value}    Step
    RETURN    ${value}
Keyword name

You can add current keyword name to the documentation using keyword.name variable.

This is documentation for '{{ keyword.name }}' keyword.

*** Keywords ***
Keyword
    Step

Other Keyword
    Step 2

*** Keywords ***
Keyword
    [Documentation]    This is documentation for 'Keyword' keyword.
    Step

Other Keyword
    [Documentation]    This is documentation for 'Other Keyword' keyword.
    Step 2