[Transformer] Format documentation

[bhirsz]

From #300

Transformer for formatting the documentation. By default it could use one style of the documentation (like Google docstring) but allow to switch to some other popular styles.

Upon consideration: allowing to pass some kind of template that would be applied to documentation.

[bhirsz]

Considering the complexity of formatting existing documentation, we cannot provide anything more than simple support such as indenting whole lines etc.

We can do more in terms of generating new documentation - for example if we have new keyword and we want to create documentation for it. We could have non-default transformer GenerateTransformer that will add documentation stubs based on content of the keyword - arguments, return values etc. By default it would only add missing documentation with the option to overwrite previous docs.

User would be able to select basic documentation styles (such as google-style) or provide their own template for the documentation (using jinja templating).

Example of the template:

{% if arguments %}
{{ c_indent }}Arguments:
{% endif %}
{% for arg in arguments %}
{{ c_indent }}{{ separator }}{{ arg }}:
{% endfor %}

{{ c_indent }}Returns:

Keyword before running transformer:

Two Arguments
    [Arguments]    ${var}    ${var2}

After:

Two Arguments
    [Documentation]
    ...
    ...    Arguments:
    ...        ${var}:
    ...        ${var2}:
    ...
    ...    Returns:
    ...
    [Arguments]    ${var}    ${var2}

[bhirsz]

For the templates I will provide basic values such as indent, continuation indent, separator (that can be provided in robotidy config or taken from defaults), and parsed arguments, return values. I need to take a look at some example documentation to see if there is need to access any extra information (for example generate special line if specific keyword is used etc).

[levlist]

Hi,

is it possible to add to the template two such fields which can insert a placeholder static user message to the documentation like "WRITE DOCUMENTATION". And another one which can insert the keyword name to the documentation. Or combining these two stuffs.

I hope I could explain my ideas well.

Examples:

    [Documentation]    WRITE DOCUMENTATION
    ...
    ...    Arguments:
    ...        ${var}:
    ...        ${var2}:
    ...
    ...    Returns:
    ...
    [Arguments]    ${var}    ${var2}


Two Arguments
    [Documentation]    Two arguments
    ...
    ...    Arguments:
    ...        ${var}:
    ...        ${var2}:
    ...
    ...    Returns:
    ...
    [Arguments]    ${var}    ${var2}```


Two Arguments
    [Documentation]    WRITE DOCUMENTATION Two arguments
    ...
    ...    Arguments:
    ...        ${var}:
    ...        ${var2}:
    ...
    ...    Returns:
    ...
    [Arguments]    ${var}    ${var2}

And that is a good question what would be better the inserted text should be the same line as the [Documentation] tag or in the next line.

[bhirsz]

Yes, if you look at the example I provided - which is from working POC - I'm already using some static text. It's "Arguments" and "Returns". User will be able to provide any kind of free text in their custom templates. And it will be covered in the future documentation but first line of the template is space right after [Documentation] marker. So user can provide something in the first line of the template and it will be displayed there or can simply (like I did in the example template) put few empty lines so the text starts below documentation marker.

[levlist]

You are right. I thought those are dedicated strings, not such kind of free text. Sorry, my bad. :-(

[bhirsz]

And for automatic field I can also provide keyword name (ie {{ keyword }}) which will help users to insert it somewhere in the template.

The main downside of using templating is that user will need to learn basics of jinja templating if he wants anything more complex than provided by default. But I think it's quite straightforward to learn (and rewarding if you apply new skills in other automation tasks). And it will be optional since robotidy will come with predefined templates already.

[bhirsz]

You are right. I thought those are dedicated strings, not such kind of free text. Sorry, my bad. :-(

Don't be sorry, , that was important part to point out and I will hightlight it in the documentation as well - since it could be not clear that you are free to input free text. The documention is often one of the most important parts of the implementation ;) (but of the irony here since we're talking about transformer for documentation :D)

[bhirsz]

GenerateDocumentation transformer was just released in Robotidy 4.0! However I recommend waiting till the Robotidy 4.0.1 is (soon) released because I introduced regression.