1 How to generate documentation
2 =============================
8 This tool uses Sphinx and read-the-doc theme. All required modules are listed in
9 src/requirements.txt. These requirements are addition to CSIT requirements
10 defined in requirements.txt.
12 The generated documentation needs Java script to be fully functional.
14 The generated documentation is in the directory _build.
17 How to generate documentation
18 -----------------------------
20 - pull the last changes from git
27 All modules which are in these directories are documented:
28 - resources/libraries/python
29 - resources/libraries/robot
32 If you add / remove / rename a module or directory to one of these
33 directories, nothing is needed to be done.
36 How to add or change info in generated documentation
37 ----------------------------------------------------
39 There are templates for
41 - Python library documentation
42 - Robot library documentation
43 - Functional tests documentation
44 - Performance tests documenation
47 You can add information you want at the beginning of the file, generated
48 documentation will be appended at the end of these files.
50 See index.rst for example. The information there was copy&pasted from fd.io
53 How to document code for perfect results
54 ----------------------------------------
56 Follow PEP8 and guidelines on wiki https://wiki.fd.io/view/CSIT/Documentation
58 This is the best practice when we use Sphinx:
65 """Module description, start with one-short-sentence-description.
67 Add more descriptive text.
69 You can add a list (there must be an empty line):
74 or numbered list (there also must be an empty line):
81 class ExampleClass(BaseClass):
82 """Start with one-short-sentence-description.
84 Add more descriptive text.
87 def example_function(parameter, param_def="def"):
88 """Start with one-short-sentence-description.
90 Add more descriptive text, and / or example.
94 followed by a blank line!
102 :param parameter: The first parameter. Capital letter at the
103 beginning, full stop at the end, 80 characters long lines.
104 :param param_def: The parameter with default value.
105 :type param: str, int, dict, ... Use python data types.
107 :raises: ValueError - describe when this exception is raised.
108 :returns: Nice string.