doc/salome/gui/GEOM/collect_geom_methods.py

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