doc/gui/build_index.py

   1 # Copyright (C) 2014-2023  CEA/DEN, EDF R&D
   2 #
   3 # This library is free software; you can redistribute it and/or
   4 # modify it under the terms of the GNU Lesser General Public
   5 # License as published by the Free Software Foundation; either
   6 # version 2.1 of the License, or (at your option) any later version.
   7 #
   8 # This library is distributed in the hope that it will be useful,
   9 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11 # Lesser General Public License for more details.
  12 #
  13 # You should have received a copy of the GNU Lesser General Public
  14 # License along with this library; if not, write to the Free Software
  15 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  16 #
  17 # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
  18 #
  19
  20 ###
  21 ## The script collects information about help documents in plugins
  22 ## and prepares building of help documentation by sphinx
  23 ###
  24
  25 import argparse
  26 import os
  27 import os.path as osp
  28 import re
  29 import shutil
  30 import sys
  31 from xml.dom.minidom import parse
  32
  33 def find_dir(src_path, cfg_file):
  34     """Find a name of a directory where the given config file exists"""
  35     entities = os.listdir(src_path)
  36     for entity in entities:
  37         path = osp.join(src_path, entity)
  38         cfg_path = osp.join(path, cfg_file)
  39         if not osp.isdir(path):
  40             continue
  41         if not osp.exists(cfg_path) and not osp.exists(cfg_path + '.in'):
  42             continue
  43         if osp.exists(osp.join(path, 'doc')):
  44             return osp.join(path, 'doc')
  45     return None
  46
  47 def main(src_dir, build_dir):
  48     """Main function"""
  49     src_path = osp.realpath(osp.join(src_dir, *[os.pardir]*2, 'src'))
  50     config_file = osp.join(src_path, 'Config', 'plugins.xml.in')
  51
  52     ## Find accessible plugins from plugins.xml configuration file
  53     processed = []
  54
  55     indices = []
  56     tui_scripts = []
  57
  58     doc = parse(config_file)
  59     plugins = doc.getElementsByTagName('plugin')
  60     for plugin in plugins:
  61         plugin_name = plugin.getAttribute('library')
  62         if not plugin_name:
  63             plugin_name = plugin.getAttribute('script')
  64         if not plugin_name or plugin_name in processed:
  65             continue
  66         config = plugin.getAttribute('configuration')
  67         if not config:
  68             continue
  69         lib_dir = find_dir(src_path, config)
  70         if lib_dir:
  71             ## Copy plugin's documenation folder to the build directory
  72             dist_dir = osp.join(build_dir, plugin_name)
  73             if osp.exists(dist_dir):
  74                 shutil.rmtree(dist_dir)
  75             shutil.copytree(lib_dir, dist_dir)
  76             ## Collect index file
  77             ## For Sphinks type of slash is important.
  78             ## Even for Windows the slash direction has to be the same
  79             indices.append(plugin_name + "/" + plugin_name + '.rst')
  80             ## Collect TUI scripts
  81             tui_files = sorted(f for f in os.listdir(lib_dir) if \
  82                                    osp.isfile(osp.join(lib_dir, f)) and re.match('TUI_.*\.rst', f))
  83             if tui_files:
  84                 tui_list_file = osp.join(dist_dir, 'TUI_examples.rst')
  85                 with open(tui_list_file, 'w') as flist:
  86                     flist.write('.. _tui_{}:\n\n'.format(plugin_name.lower()))
  87                     title = plugin_name.replace('Plugin', ' plug-in')
  88                     flist.write('{}\n'.format(title))
  89                     flist.write('{}\n\n'.format('='*len(title)))
  90                     flist.write('.. toctree::\n')
  91                     flist.write('   :titlesonly:\n')
  92                     flist.write('   :maxdepth: 1\n\n')
  93                     flist.writelines(['   {}\n'.format(i) for i in tui_files])
  94                 tui_scripts.append(osp.join('..', plugin_name, 'TUI_examples.rst'))
  95             ## Mark plugin as processed
  96             processed.append(plugin_name)
  97
  98     ## Generate index file
  99     in_file = osp.join(src_dir, 'index.rst.in')
 100     out_file = osp.join(build_dir, 'index.rst')
 101     with open(in_file, 'r') as fin, open(out_file, 'w') as fout:
 102         lines = fin.readlines()
 103         idx = lines.index('<insert here>\n')
 104         lines = lines[:idx] + ['   {}\n'.format(i) for i in indices] + lines[idx+1:]
 105         fout.writelines(lines)
 106
 107     ## Generate TUI scripts index
 108     in_file = osp.join(src_dir, 'TUI_scripts.rst.in')
 109     out_file = osp.join(build_dir, 'General', 'TUI_scripts.rst')
 110     with open(in_file, 'r') as fin, open(out_file, 'w') as fout:
 111         lines = fin.readlines()
 112         idx = lines.index('<insert here>\n')
 113         lines = lines[:idx] + ['   {}\n'.format(i) for i in tui_scripts] + lines[idx+1:]
 114         fout.writelines(lines)
 115
 116 if __name__ == '__main__':
 117     parser = argparse.ArgumentParser(description='Generate index file from source directory')
 118     parser.add_argument('build_dir', help='build directory')
 119     parser.add_argument('src_dir', help='source directory')
 120     args = parser.parse_args()
 121     sys.exit(main(args.src_dir, args.build_dir))