resources/tools/doc_gen/gen_rst.py

   1 # Copyright (c) 2018 Cisco and/or its affiliates.
   2 # Licensed under the Apache License, Version 2.0 (the "License");
   3 # you may not use this file except in compliance with the License.
   4 # You may obtain a copy of the License at:
   5 #
   6 #     http://www.apache.org/licenses/LICENSE-2.0
   7 #
   8 # Unless required by applicable law or agreed to in writing, software
   9 # distributed under the License is distributed on an "AS IS" BASIS,
  10 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  11 # See the License for the specific language governing permissions and
  12 # limitations under the License.
  13
  14
  15 from os import walk, listdir
  16 from os.path import isfile, isdir, join, getsize
  17
  18 # Temporary working directory. It is created and deleted by run_doc.sh
  19 WORKING_DIR = "tmp"
  20
  21 # Directory with resources to be documented.
  22 RESOURCES_DIR = "resources"
  23
  24 # Directory with libraries (python, robot) to be documented.
  25 LIB_DIR = "libraries"
  26
  27 # Directory with tests (func, perf) to be documented.
  28 TESTS_DIR = "tests"
  29
  30 PY_EXT = ".py"
  31 RF_EXT = ".robot"
  32
  33 PATH_PY_LIBS = join(WORKING_DIR, RESOURCES_DIR, LIB_DIR, "python")
  34 PATH_RF_LIBS = join(WORKING_DIR, RESOURCES_DIR, LIB_DIR, "robot")
  35 PATH_TESTS = join(WORKING_DIR, TESTS_DIR)
  36
  37 # Sections in rst files
  38 rst_toc = """
  39 .. toctree::
  40 """
  41
  42 rst_py_module = """
  43 .. automodule:: {}.{}
  44     :members:
  45     :undoc-members:
  46     :show-inheritance:
  47 """
  48
  49 rst_rf_suite_setup = """
  50 .. robot-settings::
  51    :source: {}
  52 """
  53
  54 rst_rf_variables = """
  55 .. robot-variables::
  56    :source: {}
  57 """
  58
  59 rst_rf_keywords = """
  60 .. robot-keywords::
  61    :source: {}
  62 """
  63
  64 rst_rf_tests = """
  65 .. robot-tests::
  66    :source: {}
  67 """
  68
  69
  70 def get_files(path, extension):
  71     """Generates the list of files to process.
  72
  73     :param path: Path to files.
  74     :param extension: Extension of files to process. If it is the empty string,
  75     all files will be processed.
  76     :type path: str
  77     :type extension: str
  78     :returns: List of files to process.
  79     :rtype: list
  80     """
  81
  82     file_list = list()
  83     for root, dirs, files in walk(path):
  84         for filename in files:
  85             if extension:
  86                 if filename.endswith(extension):
  87                     file_list.append(join(root, filename))
  88             else:
  89                 file_list.append(join(root, filename))
  90
  91     return file_list
  92
  93
  94 def create_file_name(path, start):
  95     """Create the name of rst file.
  96
  97     Example:
  98     tests.perf.rst
  99
 100     :param path: Path to a module to be documented.
 101     :param start: The first directory in path which is used in the file name.
 102     :type path: str
 103     :type start: str
 104     :returns: File name.
 105     :rtype: str
 106     """
 107     dir_list = path.split('/')
 108     start_index = dir_list.index(start)
 109     return ".".join(dir_list[start_index:-1]) + ".rst"
 110
 111
 112 def create_rst_file_names_set(files, start):
 113     """Generate a set of unique rst file names.
 114
 115     :param files: List of all files to be documented with path beginning in the
 116     working directory.
 117     :param start: The first directory in path which is used in the file name.
 118     :type files: list
 119     :type start: str
 120     :returns: Set of unique rst file names.
 121     :rtype: set
 122     """
 123     file_names = set()
 124     for file in files:
 125         file_names.add(create_file_name(file, start))
 126     return file_names
 127
 128
 129 def scan_dir(path):
 130     """Create a list of files and directories in the given directory.
 131
 132     :param path: Path to the directory.
 133     :type path: str
 134     :returns: List of directories and list of files sorted in alphabetical
 135     order.
 136     :rtype: tuple of two lists
 137     """
 138     files = list()
 139     dirs = list()
 140     items = listdir(path)
 141     for item in items:
 142         if isfile(join(path, item)) and "__init__" not in item:
 143             files.append(item)
 144         elif isdir(join(path, item)):
 145             dirs.append(item)
 146     return sorted(dirs), sorted(files)
 147
 148
 149 def write_toc(fh, path, dirs):
 150     """Write a table of contents to given rst file.
 151
 152     :param fh: File handler of the rst file.
 153     :param path: Path to package.
 154     :param dirs: List of directories to be included in ToC.
 155     :type fh: BinaryIO
 156     :type path: str
 157     :type dirs: list
 158     """
 159     fh.write(rst_toc)
 160     for dir in dirs:
 161         fh.write("    {}.{}\n".format('.'.join(path), dir))
 162
 163
 164 def write_module_title(fh, module_name):
 165     """Write the module title to the given rst file. The title will be on the
 166     second level.
 167
 168     :param fh: File handler of the rst file.
 169     :param module_name: The name of module used for title.
 170     :type fh: BinaryIO
 171     :type module_name: str
 172     """
 173     title = "{} suite".format(module_name)
 174     fh.write("\n{}\n{}\n".format(title, '-' * len(title)))
 175
 176
 177 def generate_py_rst_files():
 178     """Generate all rst files for all python modules."""
 179
 180     dirs_ignore_list = ["__pycache__", ]
 181
 182     py_libs = get_files(PATH_PY_LIBS, PY_EXT)
 183     file_names = create_rst_file_names_set(py_libs, RESOURCES_DIR)
 184
 185     for file_name in file_names:
 186         path = join(WORKING_DIR, *file_name.split('.')[:-1])
 187         dirs, files = scan_dir(path)
 188
 189         for item in dirs_ignore_list:
 190             while True:
 191                 try:
 192                     dirs.remove(item)
 193                 except ValueError:
 194                     break
 195
 196         full_path = join(WORKING_DIR, file_name)
 197         with open(full_path, mode='a') as fh:
 198             if getsize(full_path) == 0:
 199                 package = file_name.split('.')[-2]
 200                 fh.write("{}\n".format(package))
 201                 fh.write('=' * len("{}".format(package)))
 202             module_path = file_name.split('.')[:-1]
 203             if dirs:
 204                 write_toc(fh, module_path, dirs)
 205             for file in files:
 206                 module_name = file.split('.')[0]
 207                 write_module_title(fh, module_name)
 208                 fh.write(rst_py_module.format('.'.join(module_path),
 209                                               module_name))
 210
 211
 212 def generate_rf_rst_files(file_names, incl_tests=True, incl_keywords=True,
 213                           incl_suite_setup=False, incl_variables=False):
 214     """Generate rst files for the given robot modules.
 215
 216     :param file_names: List of file names to be included in the documentation
 217     (rst files).
 218     :param incl_tests: If True, tests will be included in the documentation.
 219     :param incl_keywords: If True, keywords will be included in the
 220     documentation.
 221     :param incl_suite_setup: If True, the suite setup will be included in the
 222     documentation.
 223     :param incl_variables: If True, the variables will be included in the
 224     documentation.
 225     :type file_names: set
 226     :type incl_tests: bool
 227     :type incl_keywords: bool
 228     :type incl_suite_setup: bool
 229     :type incl_variables: bool
 230     """
 231
 232     for file_name in file_names:
 233         path = join(WORKING_DIR, *file_name.split('.')[:-1])
 234         dirs, files = scan_dir(path)
 235
 236         full_path = join(WORKING_DIR, file_name)
 237         with open(full_path, mode='a') as fh:
 238             if getsize(full_path) == 0:
 239                 package = file_name.split('.')[-2]
 240                 fh.write("{}\n".format(package))
 241                 fh.write('=' * len("{}".format(package)) + '\n')
 242             module_path = file_name.split('.')[:-1]
 243             if dirs:
 244                 write_toc(fh, module_path, dirs)
 245             for file in files:
 246                 module_name = file.split('.')[0]
 247                 write_module_title(fh, module_name)
 248                 path = join(join(*module_path), module_name + RF_EXT)
 249                 if incl_suite_setup:
 250                     fh.write(rst_rf_suite_setup.format(path))
 251                 if incl_variables:
 252                     fh.write(rst_rf_variables.format(path))
 253                 if incl_keywords:
 254                     fh.write(rst_rf_keywords.format(path))
 255                 if incl_tests:
 256                     fh.write(rst_rf_tests.format(path))
 257
 258
 259 def generate_kw_rst_files():
 260     """Generate all rst files for all robot modules with keywords in libraries
 261     directory (no tests)."""
 262
 263     rf_libs = get_files(PATH_RF_LIBS, RF_EXT)
 264     file_names = create_rst_file_names_set(rf_libs, RESOURCES_DIR)
 265
 266     generate_rf_rst_files(file_names, incl_tests=False)
 267
 268
 269 def generate_tests_rst_files():
 270     """Generate all rst files for all robot modules with tests in tests
 271     directory. Include also keywords defined in these modules."""
 272
 273     tests = get_files(PATH_TESTS, RF_EXT)
 274     file_names = create_rst_file_names_set(tests, TESTS_DIR)
 275
 276     generate_rf_rst_files(file_names,
 277                           incl_suite_setup=True,
 278                           incl_variables=True)
 279
 280
 281 if __name__ == '__main__':
 282
 283     # Generate all rst files:
 284     generate_py_rst_files()
 285     generate_kw_rst_files()
 286     generate_tests_rst_files()