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