resources/tools/doc_gen/README.rst

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