Skip to content

Commit d2ff40b

Browse files
bhirszmnojek
bhirsz
and
mnojek
authored
Generate keyword documentation with new GenerateDocumentation transformer (#493)
* Add GenerateDocumentation transformer Co-authored-by: Mateusz Nojek <matnojek@gmail.com>
1 parent 54b1127 commit d2ff40b

File tree

23 files changed

+1189
-16
lines changed

23 files changed

+1189
-16
lines changed

‎docs/releasenotes/4.0.0.rst‎

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,11 @@ Robotidy 4.0.0
22
=========================================
33

44
Major release which contains multiple improvements for external transformers. There are also backward incompatible
5-
changes, including removing ``section`` option from ``NormalizeSeparators`` (replaced with ``skip_sections``).
5+
changes, including removing ``section`` option from ``NormalizeSeparators`` (replaced with ``skip_sections``). We have
6+
also added following new transformers:
7+
8+
- RemoveEmptyValues
9+
- GenerateDocumentation
610

711
You can install the latest available version by running::
812

@@ -145,6 +149,37 @@ To be more explicit, this transformer replace such values with ``${EMPTY}`` vari
145149
... ${EMPTY}
146150
... value3
147151

152+
New transformer GenerateDocumentation (#311)
153+
--------------------------------------------
154+
155+
Transformer that allows you to generate keyword documentation stubs based on the keyword data such as
156+
name, arguments or returned values. It uses Jinja templating internally and allows to define your own
157+
documentation templates. With default template (Google docstring) and following code::
158+
159+
*** Keywords ***
160+
Keyword
161+
[Arguments] ${arg}
162+
${var} ${var2} Step
163+
RETURN ${var} ${var2}
164+
165+
it will generate::
166+
167+
*** Keywords ***
168+
Keyword
169+
[Documentation]
170+
...
171+
... Arguments:
172+
... ${arg}:
173+
...
174+
... Returns:
175+
... ${var}
176+
... ${var2}
177+
[Arguments] ${arg}
178+
${var} ${var2} Step
179+
RETURN ${var} ${var2}
180+
181+
Read the transformer documentation for more details on configuring your own custom template.
182+
148183
Group comments with settings in OrderSettings (#468)
149184
----------------------------------------------------
150185

‎docs/source/transformers/GenerateDocumentation.rst‎

Lines changed: 319 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,319 @@
1+
.. _GenerateDocumentation:
2+
3+
GenerateDocumentation
4+
================================
5+
Generate keyword documentation with the documentation template.
6+
7+
.. |TRANSFORMERNAME| replace:: GenerateDocumentation
8+
.. include:: disabled_hint.txt
9+
10+
11+
By default, GenerateDocumentation uses
12+
`Google docstring <https://google.github.io/styleguide/pyguide.html#383-functions-and-methods>`_
13+
as the documentation template.
14+
15+
.. tab-set::
16+
17+
.. tab-item:: Before
18+
19+
.. code:: robotframework
20+
21+
*** Keywords ***
22+
Keyword
23+
[Arguments] ${arg}
24+
${var} ${var2} Step
25+
RETURN ${var} ${var2}
26+
27+
Keyword With ${embedded} Variable
28+
Step
29+
30+
.. tab-item:: After
31+
32+
.. code:: robotframework
33+
34+
*** Keywords ***
35+
Keyword
36+
[Documentation]
37+
...
38+
... Arguments:
39+
... ${arg}:
40+
...
41+
... Returns:
42+
... ${var}
43+
... ${var2}
44+
[Arguments] ${arg}
45+
${var} ${var2} Step
46+
RETURN ${var} ${var2}
47+
48+
Keyword With ${embedded} Variable
49+
[Documentation]
50+
...
51+
... Arguments:
52+
... ${embedded}:
53+
Step
54+
55+
Overwriting documentation
56+
--------------------------
57+
58+
The documentation will not be added if it is already present in the keyword. You can configure it
59+
by using ``overwrite`` parameter:
60+
61+
.. tab-set::
62+
63+
.. tab-item:: Before
64+
65+
.. code:: robotframework
66+
67+
*** Keywords ***
68+
Keyword With Documentation
69+
[Documentation] Short description.
70+
[Arguments] ${arg}
71+
Step
72+
73+
.. tab-item:: After (overwrite = False)
74+
75+
.. code:: robotframework
76+
77+
*** Keywords ***
78+
Keyword With Documentation
79+
[Documentation] Short description.
80+
[Arguments] ${arg}
81+
Step
82+
83+
.. tab-item:: After (overwrite = True)
84+
85+
.. code:: robotframework
86+
87+
*** Keywords ***
88+
Keyword With Documentation
89+
[Documentation]
90+
... Arguments:
91+
... ${arg}:
92+
[Arguments] ${arg}
93+
Step
94+
95+
Custom template
96+
----------------
97+
98+
Custom templates can be loaded from the file using ``doc_template`` parameter. If you pass
99+
``google`` string it will use default template::
100+
101+
> robotidy --configure GenerateDocumentation:doc_template=google src
102+
103+
Templates support `Jinja templating engine <https://jinja.palletsprojects.com/>`_ and we are providing several variables
104+
based on the keyword data. Below, there is a default template::
105+
106+
{% if keyword.arguments|length > 0 %}
107+
{{ formatting.cont_indent }}Args:
108+
{%- for arg in keyword.arguments %}
109+
{{ formatting.cont_indent }}{{ formatting.cont_indent }}{{ arg.name }}: {% endfor %}
110+
{% endif -%}
111+
{% if keyword.returns|length > 0 %}
112+
{{ formatting.cont_indent }}Returns:
113+
{%- for value in keyword.returns %}
114+
{{ formatting.cont_indent }}{{ formatting.cont_indent }}{{ value }}: {% endfor %}
115+
{% endif -%}
116+
117+
The Jinja syntax is described `here <https://jinja.palletsprojects.com/en/3.1.x/templates/>`_. You can use it as
118+
a reference to create your own template. The following subsections explain in detail possible features.
119+
120+
Path to template can be absolute or relative (to working directory or configuration file directory)::
121+
122+
> robotidy --configure GenerateDocumentation;doc_template="C:/doc_templates/template.jinja" src
123+
> robotidy --configure GenerateDocumentation:doc_template="template.jinja" src
124+
125+
Note that to pass parameter value with ``:`` (like a absolute path), you need to use ``;`` as a parameter separator.
126+
127+
.. dropdown:: First line of the documentation
128+
129+
The first line of the template is also the first line of the documentation that goes next to the ``[Documentation]`` setting.
130+
131+
.. tab-set::
132+
133+
.. tab-item:: Template
134+
135+
.. code:: text
136+
137+
First line of template
138+
Second line of example
139+
Third line.
140+
141+
.. tab-item:: Generated example
142+
143+
.. code:: robotframework
144+
145+
*** Keywords ***
146+
Keyword
147+
[Documentation] First line of template
148+
... Second line of example
149+
... Third line.
150+
Step
151+
152+
Leave the first line empty in the template if you want to start documentation from the second line.
153+
154+
.. dropdown:: Whitespace can be static or dynamic
155+
156+
Any whitespace in the template will apply to the documentation. For example you can put 4 spaces after every argument
157+
and before `->` sign:
158+
159+
.. tab-set::
160+
161+
.. tab-item:: Template
162+
163+
.. code:: text
164+
165+
Args:
166+
{%- for arg in keyword.arguments %}
167+
{{ arg.name }} ->{% endfor %}
168+
169+
.. tab-item:: Code
170+
171+
.. code:: robotframework
172+
173+
*** Keywords ***
174+
Keyword
175+
[Arguments] ${arguments} ${arg} ${arg2}
176+
Step
177+
178+
.. tab-item:: Generated example
179+
180+
.. code:: robotframework
181+
182+
*** Keywords ***
183+
Keyword
184+
[Documentation]
185+
... Args:
186+
... ${arguments} ->
187+
... ${arg} ->
188+
... ${arg2} ->
189+
[Arguments] ${arguments} ${arg} ${arg2}
190+
Step
191+
192+
Robotidy provides also ``formatting`` class that contains two variables:
193+
194+
- ``separator`` (default 4 spaces) - spacing between tokens
195+
- ``cont_indent`` (default 4 spaces) - spacing after ``...`` signs
196+
197+
You can use them in the template - and their values will be affected by your configuration::
198+
199+
{{ formatting.separator }}
200+
{{ formatting.cont_indent }}
201+
202+
.. dropdown:: Arguments data
203+
204+
Robotidy provides arguments as a list of variables in ``keyword.arguments`` variable. Every argument contains the following
205+
variables:
206+
207+
- ``name`` - name of the argument without default value (ie. ``${arg}``)
208+
- ``default`` - default value (ie. ``value``)
209+
- ``full_name`` - name with default value (ie. ``${arg} = value``)
210+
211+
You can use them in the template:
212+
213+
.. tab-set::
214+
215+
.. tab-item:: Template
216+
217+
.. code:: text
218+
219+
Arguments:
220+
{%- for arg in keyword.arguments %}
221+
{{ arg.name }} - {{ arg.default }}:{% endfor %}
222+
223+
.. tab-item:: Code
224+
225+
.. code:: robotframework
226+
227+
*** Keywords ***
228+
Keyword
229+
[Arguments] ${var} ${var2} = 2
230+
Step
231+
232+
.. tab-item:: Generated example
233+
234+
.. code:: robotframework
235+
236+
*** Keywords ***
237+
Keyword
238+
[Documentation]
239+
... Arguments:
240+
... ${var} - :
241+
... ${var2} - 2:
242+
[Arguments] ${var} ${var2} = 2
243+
Step
244+
245+
Note that you can use Jinja templating features like ``if`` blocks. For example, if you want to put ``=`` between
246+
the argument name and default value (only if default value is not empty), you can use::
247+
248+
{{ arg.name }}{% if arg.default %} = '{{ arg.default }}'{% endif %}
249+
250+
.. dropdown:: Returned values data
251+
252+
Returned values are provided as a list of variables names in ``keyword.returns`` variable.
253+
254+
.. tab-set::
255+
256+
.. tab-item:: Template
257+
258+
.. code:: text
259+
260+
Returns:
261+
{%- for value in keyword.returns %}
262+
{{ value }}:{% endfor %}
263+
264+
.. tab-item:: Code
265+
266+
.. code:: robotframework
267+
268+
*** Keywords ***
269+
Keyword
270+
${value} Step
271+
RETURN ${value}
272+
273+
.. tab-item:: Generated example
274+
275+
.. code:: robotframework
276+
277+
*** Keywords ***
278+
Keyword
279+
[Documentation]
280+
... Returns:
281+
... ${value}:
282+
${value} Step
283+
RETURN ${value}
284+
285+
.. dropdown:: Keyword name
286+
287+
You can add current keyword name to the documentation using ``keyword.name`` variable.
288+
289+
.. tab-set::
290+
291+
.. tab-item:: Template
292+
293+
.. code:: text
294+
295+
This is documentation for '{{ keyword.name }}' keyword.
296+
297+
.. tab-item:: Code
298+
299+
.. code:: robotframework
300+
301+
*** Keywords ***
302+
Keyword
303+
Step
304+
305+
Other Keyword
306+
Step 2
307+
308+
.. tab-item:: Generated example
309+
310+
.. code:: robotframework
311+
312+
*** Keywords ***
313+
Keyword
314+
[Documentation] This is documentation for 'Keyword' keyword.
315+
Step
316+
317+
Other Keyword
318+
[Documentation] This is documentation for 'Other Keyword' keyword.
319+
Step 2

‎noxfile.py‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
import nox
22

3-
43
DEFAULT_PYTHON_VERSION = "3.11"
54

65
UNIT_TEST_PYTHON_VERSIONS = ["3.7", "3.8", "3.9", "3.10", "3.11"]

‎robotidy/api.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,7 @@ def convert_transformers_config(
8888
exclude = config.get("exclude", None)
8989
extend_exclude = config.get("extend_exclude", None)
9090
reruns = config.get("reruns", 0)
91+
config_directory = config.get("config_directory", None)
9192
exclude = utils.validate_regex(exclude if exclude is not None else files.DEFAULT_EXCLUDES)
9293
extend_exclude = utils.validate_regex(extend_exclude)
9394
global_skip = get_skip_config(config)
@@ -110,6 +111,7 @@ def convert_transformers_config(
110111
color=False,
111112
language=language,
112113
reruns=reruns,
114+
config_directory=config_directory,
113115
)
114116
return app.Robotidy(config=configuration)
115117

0 commit comments

Comments
 (0)