doc/salome/gui/SMESH/collect_mesh_methods.py

   1 #!/usr/bin/env python
   2 #  -*- coding: iso-8859-1 -*-
   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_mesh_methods.py
  25 # Author: Vadim SANDLER, Open CASCADE S.A.S (vadim.sandler@opencascade.com)
  26 #
  27 #################################################################################
  28 #
  29 # Extraction of the meshing algorithm classes
  30 # dynamically added by the plug-in to the Mesh
  31 # class.
  32 #
  33 # This script is intended for internal usage - only
  34 # for generatation of the extra developer documentation for
  35 # the meshing plug-in(s).
  36 #
  37 # Usage:
  38 #       collect_mesh_methods.py <plugin_name>
  39 # where
  40 #   <plugin_name> is a name of the plug-in module
  41 #
  42 # Notes:
  43 # - the script is supposed to be run in correct environment
  44 # i.e. PYTHONPATH, SMESH_MeshersList and other important
  45 # variables are set properly; otherwise the script will fail.
  46 #
  47 ################################################################################
  48 import sys
  49
  50 def main(plugin_name, dummymeshhelp = True, output_file = "smeshBuilder.py", format = "doxygen"):
  51     plugin_module_name  = plugin_name + "Builder"
  52     plugin_module       = "salome.%s.%s" % (plugin_name, plugin_module_name)
  53     try:
  54         exec( "from salome.smesh.smeshBuilder import *")
  55         exec( "import %s" % plugin_module )
  56         exec( "mod = %s" % plugin_module )
  57         methods = {}
  58         for attr in dir( mod ):
  59             if attr.startswith( '_' ): continue
  60             algo = getattr( mod, attr )
  61             if type( algo ).__name__ == 'classobj' and hasattr( algo, "meshMethod" ):
  62                 method = getattr( algo, "meshMethod" )
  63                 if method not in methods: methods[ method ] = []
  64                 methods[ method ].append( algo )
  65                 pass
  66             pass
  67         if methods:
  68             output = []
  69             if dummymeshhelp:
  70                 if format == "doxygen":
  71                     output.append( "## @package smeshBuilder" )
  72                     output.append( "#  Documentation of the methods dynamically added by the " + plugin_name + " meshing plug-in to the Mesh class." )
  73                     output.append( "" )
  74                 elif format == "sphinx":
  75                     output.append( '"""' )
  76                     output.append( 'Documentation of the methods dynamically added by the ' + plugin_name + ' meshing plug-in to the Mesh class.' )
  77                     output.append( '"""' )
  78                     output.append( '' )
  79                 pass
  80             if format == "doxygen":
  81                 output.append( "## This class allows defining and managing a mesh." )
  82                 output.append( "#" )
  83             elif format == "sphinx":
  84                 output.append( "class Mesh:" )
  85                 output.append( '    """' )
  86                 output.append( '    This class allows defining and managing a mesh.' )
  87                 output.append( '    ' )
  88             if dummymeshhelp:
  89                 # Add dummy Mesh help
  90                 # This is supposed to be done when generating documentation for meshing plug-ins
  91                 if format == "doxygen":
  92                     output.append( "#  @note The documentation below does not provide complete description of class @b %Mesh" )
  93                     output.append( "#  from @b smeshBuilder package. This documentation provides only information about" )
  94                     output.append( "#  the methods dynamically added to the %Mesh class by the " + plugin_name + " plugin" )
  95                     output.append( "#  For more details on the %Mesh class, please refer to the SALOME %Mesh module" )
  96                     output.append( "#  documentation." )
  97                 elif format == "sphinx":
  98                     output.append( '    The documentation below does not provide complete description of class @b %Mesh' )
  99                     output.append( '    from @b smeshBuilder package. This documentation provides only information about' )
 100                     output.append( '    the methods dynamically added to the %Mesh class by the " + plugin_name + " plugin' )
 101                     output.append( '    For more details on the %Mesh class, please refer to the SALOME %Mesh module' )
 102                     output.append( '    documentation.' )
 103                     output.append( '    """' )
 104                     output.append( '    ' )
 105                 pass
 106             else:
 107                 # Extend documentation for Mesh class with information about dynamically added methods.
 108                 # This is supposed to be done only when building documentation for SMESH module
 109                 if format ==  "doxygen":
 110                     output.append( "#  @note Some methods are dynamically added to the @b %Mesh class in runtime by meshing " )
 111                     output.append( "#  plug-in modules. If you fail to find help on some methods in the documentation of SMESH module, " )
 112                     output.append( "#  try to look into the documentation for the meshing plug-ins." )
 113                 elif format == "sphinx":
 114                     output.append( "    Note:")
 115                     output.append( "        Some methods are dynamically added to the @b %Mesh class in runtime by meshing " )
 116                     output.append( "        plug-in modules. If you fail to find help on some methods in the documentation of SMESH module, " )
 117                     output.append( "        try to look into the documentation for the meshing plug-ins." )
 118                     output.append( '    """' )
 119                     output.append( '    ' )
 120                 pass
 121             if format == "doxygen":
 122                 output.append( "class Mesh:" )
 123             for method in methods:
 124                 docHelper = ""
 125                 for algo in methods[ method ]:
 126                     if hasattr( algo, "docHelper" ): docHelper = getattr( algo, "docHelper" )
 127                     if docHelper: break
 128                     pass
 129                 if not docHelper: docHelper = "Creates new algorithm."
 130                 if format == "doxygen":
 131                     output.append( " ## %s" % docHelper )
 132                     output.append( " #" )
 133                     output.append( " #  This method is dynamically added to %Mesh class by the meshing plug-in(s). " )
 134                     output.append( " #" )
 135                     output.append( " #  If the optional @a geom_shape parameter is not set, this algorithm is global (applied to whole mesh)." )
 136                     output.append( " #  Otherwise, this algorithm defines a submesh based on @a geom_shape subshape." )
 137                     output.append( " #  @param algo_type type of algorithm to be created; allowed values are specified by classes implemented by plug-in" )
 138                     output.append( " #  @param geom_shape if defined, the subshape to be meshed (GEOM_Object)" )
 139                     output.append( " #  @return An instance of Mesh_Algorithm sub-class according to the specified @a algo_type, see " )
 140                     output.append( " #  %s" % ", ".join( [ "%s.%s" % ( plugin_module_name, algo.__name__ ) for algo in methods[ method ] ] ) )
 141                     output.append( " def %s(algo_type, geom_shape=0):" % method )
 142                     output.append( "   pass" )
 143                 elif format == "sphinx":
 144                     output.append( '    def %s(algo_type, geom_shape=0):' % method )
 145                     output.append( '        """' )
 146                     output.append( '        %s' % docHelper )
 147                     output.append( '        ' )
 148                     output.append( '        This method is dynamically added to :class:`Mesh <smeshBuilder.Mesh>` class by the meshing plug-in(s). ' )
 149                     output.append( '        ' )
 150                     output.append( '        If the optional *geom_shape* parameter is not set, this algorithm is global (applied to whole mesh).' )
 151                     output.append( '        Otherwise, this algorithm defines a submesh based on *geom_shape* subshape.' )
 152                     output.append( '        ' )
 153                     output.append( '        Parameters:' )
 154                     output.append( '            algo_type: type of algorithm to be created; allowed values are specified by classes implemented by plug-in' )
 155                     output.append( '            geom_shape (GEOM_Object): if defined, the subshape to be meshed' )
 156                     output.append( '        ' )
 157                     output.append( '        Returns:')
 158                     output.append( '            An instance of Mesh_Algorithm sub-class according to the specified *algo_type*, see ' )
 159                     output.append( '            %s' % ", ".join( [ ":class:`~%s.%s`" % ( plugin_module_name, algo.__name__ ) for algo in methods[ method ] ] ) )
 160                     output.append( '        """' )
 161                     output.append( '        pass' )
 162                 pass
 163             f = open(output_file, "w")
 164             for line in output: f.write( line + "\n" )
 165             f.close()
 166             pass
 167         pass
 168     except Exception, e:
 169         print e
 170         pass
 171     pass
 172
 173 if __name__ == "__main__":
 174     import optparse
 175     parser = optparse.OptionParser(usage="%prog [options] plugin")
 176     h  = "Output file (smesh.py by default)"
 177     parser.add_option("-o", "--output", dest="output",
 178                       action="store", default=None, metavar="file",
 179                       help=h)
 180     h  = "If this option is True, dummy help for Mesh class is added. "
 181     h += "This option should be False (default) when building documentation for SMESH module "
 182     h += "and True when building documentation for meshing plug-ins."
 183     parser.add_option("-d", "--dummy-mesh-help", dest="dummymeshhelp",
 184                       action="store_true", default=False,
 185                       help=h)
 186     h = "Format of the documentation strings in the output file. Possible values are: "
 187     h+= "'doxygen' - documentation strings are generated in the doxygen format, before a method defenition."
 188     h+= "'sphinx' - documentation strings are generated in the sphinx format, after a method defenition."
 189     parser.add_option("-f", "--format", dest="format",
 190                       action="store", default="doxygen", help=h)
 191
 192     (options, args) = parser.parse_args()
 193
 194     if len( args ) < 1: sys.exit("Plugin name is not specified")
 195     main( args[0], options.dummymeshhelp, options.output, options.format )
 196     pass