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 tokenscont_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