1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
|
How to generate documentation
=============================
Requirements
------------
This tool uses Sphinx and read-the-doc theme. All required modules are listed in
src/requirements.txt. These requirements are addition to CSIT requirements
defined in requirements.txt.
The generated documentation needs Java script to be fully functional.
The generated documentation is in the directory _build.
How to generate documentation
-----------------------------
- pull the last changes from git
- run: ./run_doc.sh
What is documented
------------------
All modules which are in these directories are documented:
- resources/libraries/python
- resources/libraries/robot
- tests
If you add / remove / rename a module or directory to one of these
directories, nothing is needed to be done.
How to add or change info in generated documentation
----------------------------------------------------
There are templates for
- index
- Python library documentation
- Robot library documentation
- Functional tests documentation
- Performance tests documenation
in src/ directory.
You can add information you want at the beginning of the file, generated
documentation will be appended at the end of these files.
See index.rst for example. The information there was copy&pasted from fd.io
How to document code for perfect results
----------------------------------------
Follow PEP8 and guidelines on wiki https://wiki.fd.io/view/CSIT/Documentation
This is the best practice when we use Sphinx:
Python code
+++++++++++
.. code:: python
"""Module description, start with one-short-sentence-description.
Add more descriptive text.
You can add a list (there must be an empty line):
- item,
- second item.
or numbered list (there also must be an empty line):
#. The first item,
#. The second item.
"""
class ExampleClass(BaseClass):
"""Start with one-short-sentence-description.
Add more descriptive text.
"""
def example_function(parameter, param_def="def"):
"""Start with one-short-sentence-description.
Add more descriptive text, and / or example.
:Example:
followed by a blank line!
You can use also:
.. seealso:: blabla
.. warnings:: blabla
.. note:: blabla
.. todo:: blabla
:param parameter: The first parameter. Capital letter at the
beginning, full stop at the end, 80 characters long lines.
:param param_def: The parameter with default value.
:type param: str, int, dict, ... Use python data types.
:type param_def: str
:raises: ValueError - describe when this exception is raised.
:returns: Nice string.
:rtype: str
"""
Robot code
++++++++++
TBD
|
