doc/salome/gui/GEOM/collect_geom_methods.py

   1 #!/usr/bin/env python3
   2 # Copyright (C) 2012-2023  CEA/DEN, EDF R&D, OPEN CASCADE
   3 #
   4 # This library is free software; you can redistribute it and/or
   5 # modify it under the terms of the GNU Lesser General Public
   6 # License as published by the Free Software Foundation; either
   7 # version 2.1 of the License, or (at your option) any later version.
   8 #
   9 # This library is distributed in the hope that it will be useful,
  10 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12 # Lesser General Public License for more details.
  13 #
  14 # You should have received a copy of the GNU Lesser General Public
  15 # License along with this library; if not, write to the Free Software
  16 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  17 #
  18 # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
  19 #
  20
  21 #################################################################################
  22 #
  23 # File:   collect_geom_methods.py
  24 # Author: Roman NIKOLAEV, Open CASCADE S.A.S (roman.nikolaev@opencascade.com)
  25 #
  26 #################################################################################
  27 #
  28 # Extraction of the methods dynamically added by the Geometry
  29 # module plug-in(s) to the geomBuilder class.
  30 #
  31 # This script is intended for internal usage - only
  32 # for generatation of the extra developer documentation for
  33 # the Geometry module plug-in(s).
  34 #
  35 # Usage:
  36 #       collect_geom_methods.py <plugin_name>
  37 # where
  38 #   <plugin_name> is a name of the plug-in module
  39 #
  40 # Notes:
  41 # - the script is supposed to be run in correct environment
  42 # i.e. PYTHONPATH, GEOM_PluginsList and other important
  43 # variables are set properly; otherwise the script will fail.
  44 #
  45 ################################################################################
  46
  47 import sys
  48 import inspect
  49
  50 def generate(plugin_name, output):
  51     def get_functions(amodule):
  52         for attr in dir(amodule):
  53           if attr.startswith( '_' ): continue # skip an internal methods
  54           item = getattr(amodule, attr)
  55           if inspect.isfunction(item):
  56               yield item
  57               pass
  58           pass
  59
  60     plugin_module_name = plugin_name + "Builder"
  61     plugin_module = "salome.{}.{}".format(plugin_name, plugin_module_name)
  62     import_str = "from salome.{} import {}".format(plugin_name, plugin_module_name)
  63     execLine = "from salome.{} import {}\n" \
  64                "import {}\n" \
  65                "mod = {}".format(plugin_name, plugin_module_name, plugin_module, plugin_module)
  66     print(execLine)
  67     namespace = {}
  68     exec(execLine , namespace)
  69
  70     for function in get_functions(namespace["mod"]):
  71         comments = inspect.getcomments(function)
  72         if comments:
  73             comments = comments.strip().split("\n")
  74             comments = "\t" + "\n\t".join(comments)
  75             output.append(comments)
  76             pass
  77         sources = inspect.getsource(function)
  78         if sources is not None:
  79             sources_list = sources.split("\n")
  80             sources_new_list = []
  81             found = False
  82             for item in sources_list:
  83                 if '"""' in item:
  84                     if found == True:
  85                         found = False
  86                         continue
  87                     else:
  88                         found = True
  89                         continue
  90                         pass
  91                     pass
  92                 if found == False:
  93                     sources_new_list.append(item)
  94                     pass
  95                 pass
  96             sources = "\n".join(sources_new_list)
  97             sources = "\t" + sources.replace("\n", "\n\t")
  98             output.append(sources)
  99             pass
 100         pass
 101     pass
 102
 103 if __name__ == "__main__":
 104     import argparse
 105     parser = argparse.ArgumentParser()
 106     h  = "Output file (geomBuilder.py by default)"
 107     parser.add_argument("-o", "--output", dest="output",
 108                         action="store", default='geomBuilder.py', metavar="file",
 109                         help=h)
 110     h  = "If this option is True, dummy help for geomBuiler class is added. "
 111     h += "This option should be False (default) when building documentation for Geometry module "
 112     h += "and True when building documentation for Geometry module plug-ins."
 113     parser.add_argument("-d", "--dummy-geom-help", dest="dummygeomhelp",
 114                         action="store_true", default=False,
 115                         help=h)
 116     parser.add_argument("plugin", nargs='+', help='Name of plugin')
 117     args = parser.parse_args()
 118
 119     plugins_names = " ".join(args.plugin) + 'plugin'
 120     if len(args.plugin) > 1:
 121         plugins_names += 's'
 122     output = []
 123     if args.dummygeomhelp:
 124         output.append("## @package geomBuilder")
 125         output.append("#  Documentation of the methods dynamically added by the " + plugins_names + " to the @b %geomBuilder class.")
 126         # Add dummy Geometry help
 127         # This is supposed to be done when generating documentation for Geometry module plug-ins
 128         output.append("#  @note The documentation below does not provide complete description of class @b %geomBuilder")
 129         output.append("#  from @b geomBuilder package. This documentation provides only information about")
 130         output.append("#  the methods dynamically added to the %geomBuilder class by the " + plugins_names + ".")
 131         output.append("#  For more details on the %geomBuilder class, please refer to the SALOME %Geometry module")
 132         output.append("#  documentation.")
 133         pass
 134     else:
 135         # Extend documentation for geomBuilder class with information about dynamically added methods.
 136         # This is supposed to be done only when building documentation for Geometry module
 137         output.append("## @package geomBuilder")
 138         output.append("#  @note Some methods are dynamically added to the @b %geomBuilder class in runtime by the")
 139         output.append("#  plug-in modules. If you fail to find help on some methods in the documentation of Geometry module, ")
 140         output.append("#  try to look into the documentation for the Geometry module plug-ins.")
 141         pass
 142     output.append("class geomBuilder():")
 143
 144     for plugin_name in args.plugin:
 145        generate( plugin_name, output )
 146        pass
 147
 148     with open(args.output, "w", encoding='utf8') as f:
 149         f.write('\n'.join(output))