2 # -*- coding: iso-8859-1 -*-
3 # Copyright (C) 2012-2016 CEA/DEN, EDF R&D, OPEN CASCADE
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.
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.
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
19 # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
22 #################################################################################
24 # File: collect_mesh_methods.py
25 # Author: Vadim SANDLER, Open CASCADE S.A.S (vadim.sandler@opencascade.com)
27 #################################################################################
29 # Extraction of the meshing algorithm classes
30 # dynamically added by the plug-in to the Mesh
33 # This script is intended for internal usage - only
34 # for generatation of the extra developer documentation for
35 # the meshing plug-in(s).
38 # collect_mesh_methods.py <plugin_name>
40 # <plugin_name> is a name of the plug-in module
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.
47 ################################################################################
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)
54 exec( "from salome.smesh.smeshBuilder import *")
55 exec( "import %s" % plugin_module )
56 exec( "mod = %s" % plugin_module )
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 )
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." )
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( '"""' )
80 if format == "doxygen":
81 output.append( "## This class allows defining and managing a mesh." )
83 elif format == "sphinx":
84 output.append( "class Mesh:" )
85 output.append( ' """' )
86 output.append( ' This class allows defining and managing a mesh.' )
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( ' """' )
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( ' """' )
121 if format == "doxygen":
122 output.append( "class Mesh:" )
123 for method in methods:
125 for algo in methods[ method ]:
126 if hasattr( algo, "docHelper" ): docHelper = getattr( algo, "docHelper" )
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 (see below)" )
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 )
148 output.append( ' This method is dynamically added to **Mesh** class by the meshing plug-in(s). ' )
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.' )
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 (see below)' )
155 output.append( ' geom_shape (GEOM_Object): if defined, the subshape to be meshed' )
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' )
163 f = open(output_file, "w")
164 for line in output: f.write( line + "\n" )
173 if __name__ == "__main__":
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",
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,
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)
192 (options, args) = parser.parse_args()
194 if len( args ) < 1: sys.exit("Plugin name is not specified")
195 main( args[0], options.dummymeshhelp, options.output, options.format )