aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorTibor Frank <tifrank@cisco.com>2018-07-10 14:31:43 +0200
committerTibor Frank <tifrank@cisco.com>2018-07-10 14:31:43 +0200
commit7d3d925e126384ec5ee463422c240e284f9cabe3 (patch)
tree84d0e3be50facd55ac28518ce0e907fd6539fe58
parent28ac3a22615e19cafa7358508a24a9bd9b287544 (diff)
CSIT-1189: Add suite setup to source code documentation
Change-Id: I0cc435ecacaeb5f9e8fd5c67f495166a1abd2e91 Signed-off-by: Tibor Frank <tifrank@cisco.com>
-rwxr-xr-xresources/tools/doc_gen/gen_rst.py43
-rwxr-xr-xresources/tools/doc_gen/run_doc.sh2
2 files changed, 33 insertions, 12 deletions
diff --git a/resources/tools/doc_gen/gen_rst.py b/resources/tools/doc_gen/gen_rst.py
index 898f215b1b..3d04568de2 100755
--- a/resources/tools/doc_gen/gen_rst.py
+++ b/resources/tools/doc_gen/gen_rst.py
@@ -1,6 +1,4 @@
-#!/usr/bin/python
-
-# Copyright (c) 2016 Cisco and/or its affiliates.
+# Copyright (c) 2018 Cisco and/or its affiliates.
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at:
@@ -48,6 +46,16 @@ rst_py_module = """
:show-inheritance:
"""
+rst_rf_suite_setup = """
+.. robot-settings::
+ :source: {}
+"""
+
+rst_rf_variables = """
+.. robot-variables::
+ :source: {}
+"""
+
rst_rf_keywords = """
.. robot-keywords::
:source: {}
@@ -145,7 +153,7 @@ def write_toc(fh, path, dirs):
:param fh: File handler of the rst file.
:param path: Path to package.
:param dirs: List of directories to be included in ToC.
- :type fh: file
+ :type fh: BinaryIO
:type path: str
:type dirs: list
"""
@@ -160,7 +168,7 @@ def write_module_title(fh, module_name):
:param fh: File handler of the rst file.
:param module_name: The name of module used for title.
- :type fh: file
+ :type fh: BinaryIO
:type module_name: str
"""
title = "{} suite".format(module_name)
@@ -202,17 +210,24 @@ def generate_py_rst_files():
module_name))
-def generate_rf_rst_files(file_names, incl_tests=True, incl_keywords=True):
+def generate_rf_rst_files(file_names, incl_tests=True, incl_keywords=True,
+ incl_suite_setup=False, incl_variables=False):
"""Generate rst files for the given robot modules.
:param file_names: List of file names to be included in the documentation
(rst files).
- :param incl_tests: If true, tests will be included in the documentation.
- :param incl_keywords: If true, keywords will be included in the
+ :param incl_tests: If True, tests will be included in the documentation.
+ :param incl_keywords: If True, keywords will be included in the
+ documentation.
+ :param incl_suite_setup: If True, the suite setup will be included in the
+ documentation.
+ :param incl_variables: If True, the variables will be included in the
documentation.
:type file_names: set
:type incl_tests: bool
:type incl_keywords: bool
+ :type incl_suite_setup: bool
+ :type incl_variables: bool
"""
for file_name in file_names:
@@ -232,10 +247,14 @@ def generate_rf_rst_files(file_names, incl_tests=True, incl_keywords=True):
module_name = file.split('.')[0]
write_module_title(fh, module_name)
path = join(join(*module_path), module_name + RF_EXT)
- if incl_tests:
- fh.write(rst_rf_tests.format(path))
+ if incl_suite_setup:
+ fh.write(rst_rf_suite_setup.format(path))
+ if incl_variables:
+ fh.write(rst_rf_variables.format(path))
if incl_keywords:
fh.write(rst_rf_keywords.format(path))
+ if incl_tests:
+ fh.write(rst_rf_tests.format(path))
def generate_kw_rst_files():
@@ -255,7 +274,9 @@ def generate_tests_rst_files():
tests = get_files(PATH_TESTS, RF_EXT)
file_names = create_rst_file_names_set(tests, TESTS_DIR)
- generate_rf_rst_files(file_names)
+ generate_rf_rst_files(file_names,
+ incl_suite_setup=True,
+ incl_variables=True)
if __name__ == '__main__':
diff --git a/resources/tools/doc_gen/run_doc.sh b/resources/tools/doc_gen/run_doc.sh
index ca955cc6c4..523b4ae505 100755
--- a/resources/tools/doc_gen/run_doc.sh
+++ b/resources/tools/doc_gen/run_doc.sh
@@ -39,7 +39,7 @@ pip install -r ${WORKING_DIR}/requirements.txt
export PYTHONPATH=`pwd`
# Generate rst files:
-./gen_rst.py
+python gen_rst.py
# Remove all rst files from ./${WORKING_DIR}/env directory - we do not need them
find ./${WORKING_DIR}/env -type f -name '*.rst' | xargs rm -f