aboutsummaryrefslogtreecommitdiffstats
path: root/resources/tools/doc_gen/README.rst
diff options
context:
space:
mode:
authorTibor Frank <tifrank@cisco.com>2016-11-23 09:42:29 +0100
committerPeter Mikus <pmikus@cisco.com>2016-11-28 07:30:55 +0000
commit4dadc7a005ca99aa5a14ac650e9aa187cea10619 (patch)
tree2fc5ac6e8a875dfbf223c4789e24f3bab0b689bc /resources/tools/doc_gen/README.rst
parent4bda4f8b55b0d431b514663e8e90fccd97ad31d4 (diff)
CSIT-474: CSIT doc auto-generation
- See resources/tools/doc_gen/README.rst for details Change-Id: Ie5704c93a41e456d65fcd6df2d9d8c96987deebb Signed-off-by: Tibor Frank <tifrank@cisco.com>
Diffstat (limited to 'resources/tools/doc_gen/README.rst')
-rw-r--r--resources/tools/doc_gen/README.rst116
1 files changed, 116 insertions, 0 deletions
diff --git a/resources/tools/doc_gen/README.rst b/resources/tools/doc_gen/README.rst
new file mode 100644
index 0000000000..57771e80d5
--- /dev/null
+++ b/resources/tools/doc_gen/README.rst
@@ -0,0 +1,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