From 7d3d925e126384ec5ee463422c240e284f9cabe3 Mon Sep 17 00:00:00 2001
From: Tibor Frank <tifrank@cisco.com>
Date: Tue, 10 Jul 2018 14:31:43 +0200
Subject: [PATCH] CSIT-1189: Add suite setup to source code documentation

Change-Id: I0cc435ecacaeb5f9e8fd5c67f495166a1abd2e91
Signed-off-by: Tibor Frank <tifrank@cisco.com>
---
 resources/tools/doc_gen/gen_rst.py | 43 ++++++++++++++++++++++++++++----------
 resources/tools/doc_gen/run_doc.sh |  2 +-
 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
-- 
2.16.6