From 7d3d925e126384ec5ee463422c240e284f9cabe3 Mon Sep 17 00:00:00 2001 From: Tibor Frank Date: Tue, 10 Jul 2018 14:31:43 +0200 Subject: CSIT-1189: Add suite setup to source code documentation Change-Id: I0cc435ecacaeb5f9e8fd5c67f495166a1abd2e91 Signed-off-by: Tibor Frank --- resources/tools/doc_gen/gen_rst.py | 43 ++++++++++++++++++++++++++++---------- resources/tools/doc_gen/run_doc.sh | 2 +- 2 files changed, 33 insertions(+), 12 deletions(-) (limited to 'resources/tools/doc_gen') 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 -- cgit 1.2.3-korg