Salome HOME
0021746: EDF 2135 GEOM: Unification of Python documentations
authormpa <mpa@opencascade.com>
Fri, 14 Mar 2014 05:37:50 +0000 (09:37 +0400)
committermpa <mpa@opencascade.com>
Fri, 14 Mar 2014 05:37:50 +0000 (09:37 +0400)
doc/CMakeLists.txt
doc/docutils/CMakeLists.txt [deleted file]
doc/docutils/conf.py.in [deleted file]
doc/docutils/docapi.rst [deleted file]
doc/docutils/index.rst [deleted file]
doc/docutils/overview.rst [deleted file]
doc/salome/gui/SMESH/CMakeLists.txt
doc/salome/gui/SMESH/doxyfile_py.in
doc/salome/gui/SMESH/input/index.doc
doc/salome/gui/SMESH/input/smeshpy_interface.doc
src/SMESH_PY/smeshstudytools.py

index fc259fe..27aa573 100755 (executable)
@@ -21,4 +21,3 @@
 #
 
 ADD_SUBDIRECTORY(salome)
-ADD_SUBDIRECTORY(docutils)
diff --git a/doc/docutils/CMakeLists.txt b/doc/docutils/CMakeLists.txt
deleted file mode 100755 (executable)
index d9cc0e3..0000000
+++ /dev/null
@@ -1,36 +0,0 @@
-# Copyright (C) 2012-2014  CEA/DEN, EDF R&D, OPEN CASCADE
-#
-# This library is free software; you can redistribute it and/or
-# modify it under the terms of the GNU Lesser General Public
-# License as published by the Free Software Foundation; either
-# version 2.1 of the License, or (at your option) any later version.
-#
-# This library is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-# Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public
-# License along with this library; if not, write to the Free Software
-# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
-#
-# See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
-#
-
-SALOME_CONFIGURE_FILE(conf.py.in conf.py)
-
-SET(_cmd_options -c ${CMAKE_CURRENT_BINARY_DIR} -b html -d doctrees -D latex_paper_size=a4 ${CMAKE_CURRENT_SOURCE_DIR} docutils)
-
-# This macro mainly prepares the environment in which sphinx should run:
-# this sets the PYTHONPATH and LD_LIBRARY_PATH to include OMNIORB, DOCUTILS, SETUPTOOLS, etc ...
-SALOME_GENERATE_ENVIRONMENT_SCRIPT(_cmd env_script "${SPHINX_EXECUTABLE}" "${_cmd_options}")            
-
-ADD_CUSTOM_TARGET(html_docs COMMAND ${_cmd})
-
-INSTALL(CODE "EXECUTE_PROCESS(COMMAND \"${CMAKE_COMMAND}\" --build ${PROJECT_BINARY_DIR} --target html_docs)")
-INSTALL(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/docutils DESTINATION ${SALOME_INSTALL_DOC}/tui/SMESH)
-INSTALL(FILES ${PROJECT_SOURCE_DIR}/doc/salome/tui/images/head.png ${PROJECT_SOURCE_DIR}/doc/salome/tui/images/smeshscreen.png 
-        DESTINATION ${SALOME_INSTALL_DOC}/tui/SMESH)
-
-SET(make_clean_files docutils doctrees)
-SET_DIRECTORY_PROPERTIES(PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES "${make_clean_files}")        
diff --git a/doc/docutils/conf.py.in b/doc/docutils/conf.py.in
deleted file mode 100644 (file)
index e87a7a0..0000000
+++ /dev/null
@@ -1,200 +0,0 @@
-# -*- coding: iso-8859-1 -*-
-#
-# yacs documentation build configuration file, created by
-# sphinx-quickstart on Fri Aug 29 09:57:25 2008.
-#
-# This file is execfile()d with the current directory set to its containing dir.
-#
-# The contents of this file are pickled, so don't put values in the namespace
-# that aren't pickleable (module imports are okay, they're removed automatically).
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
-import sys, os
-
-# If your extensions are in another directory, add it here. If the directory
-# is relative to the documentation root, use os.path.abspath to make it
-# absolute, like shown here.
-#sys.path.append(os.path.abspath('.'))
-
-# General configuration
-# ---------------------
-
-# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc']
-
-# Uncomment the following line to build the links with Python documentation
-# (you might need to set http_proxy environment variable for this to work)
-#extensions += ['sphinx.ext.intersphinx']
-
-# Intersphinx mapping to add links to modules and objects in the Python
-# standard library documentation
-intersphinx_mapping = {'http://docs.python.org': None}
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix of source filenames.
-source_suffix = '.rst'
-
-# The encoding of source files.
-source_encoding = 'utf-8'
-
-# The master toctree document.
-master_doc = 'index'
-
-# General information about the project.
-project = 'SMESH python packages'
-copyright = '2010-2014 EDF R&D'
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = '@SALOMESMESH_VERSION@'
-# The full version, including alpha/beta/rc tags.
-release = '@SALOMESMESH_VERSION@'
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-language = 'en'
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#today = ''
-# Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
-
-# List of documents that shouldn't be included in the build.
-#unused_docs = []
-
-# List of directories, relative to source directory, that shouldn't be searched
-# for source files.
-exclude_trees = ['.build','ref','images','CVS','.svn']
-
-# The reST default role (used for this markup: `text`) to use for all documents.
-#default_role = None
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-#show_authors = False
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-
-# Options for HTML output
-# -----------------------
-
-# The theme to use for HTML and HTML Help pages.  Major themes that come with
-# Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'default'
-#html_theme = 'nature'
-#html_theme = 'agogo'
-#html_theme = 'sphinxdoc'
-#html_theme = 'omadoc'
-
-# Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = ['themes']
-
-# The name for this set of Sphinx documents.  If None, it defaults to
-# "<project> v<release> documentation".
-#html_title = None
-
-# A shorter title for the navigation bar.  Default is the same as html_title.
-#html_short_title = None
-
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-#html_logo = None
-
-# The name of an image file (within the static path) to use as favicon of the
-# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-#html_favicon = None
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-#html_static_path = ['_static']
-
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-#html_additional_pages = {}
-
-# If false, no module index is generated.
-html_use_modindex = False
-
-# If false, no index is generated.
-#html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-#html_split_index = False
-
-# If true, the reST sources are included in the HTML build as _sources/<name>.
-html_copy_source = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it.  The value of this option must be the
-# base URL from which the finished HTML is served.
-#html_use_opensearch = ''
-
-# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = ''
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'smeshpydoc'
-
-
-# Options for LaTeX output
-# ------------------------
-
-# The paper size ('letter' or 'a4').
-latex_paper_size = 'a4'
-
-# The font size ('10pt', '11pt' or '12pt').
-latex_font_size = '10pt'
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, document class [howto/manual]).
-latex_documents = [
-  ('index', 'smeshpy.tex', 'Documentation of the SMESH python packages', 'EDF R\&D', 'manual')
-]
-
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-latex_logo = '@CMAKE_CURRENT_SOURCE_DIR@/../salome/tui/images/head.png'
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-#latex_use_parts = True
-
-# Additional stuff for the LaTeX preamble.
-#latex_preamble = ''
-
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
-
-# If false, no module index is generated.
-latex_use_modindex = False
diff --git a/doc/docutils/docapi.rst b/doc/docutils/docapi.rst
deleted file mode 100644 (file)
index b39c124..0000000
+++ /dev/null
@@ -1,17 +0,0 @@
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- Documentation of the programming interface (API)
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-This section describes the python packages and modules of the
-``salome.smesh`` python package. The main part is generated from the
-code documentation included in source python files.
-
-:mod:`salome.smesh` -- Package containing the SMESH python utilities
-====================================================================
-
-:mod:`smeshstudytools` -- Tools to access SMESH objects in the study
---------------------------------------------------------------------
-
-.. automodule:: salome.smesh.smeshstudytools
-   :members:
diff --git a/doc/docutils/index.rst b/doc/docutils/index.rst
deleted file mode 100644 (file)
index 4863e82..0000000
+++ /dev/null
@@ -1,10 +0,0 @@
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- Documentation of the SMESH python package
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-.. toctree::
-   :maxdepth: 3
-
-   overview.rst
-   docapi.rst
diff --git a/doc/docutils/overview.rst b/doc/docutils/overview.rst
deleted file mode 100644 (file)
index ce82cc8..0000000
+++ /dev/null
@@ -1,24 +0,0 @@
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-General presentation of the SMESH python package
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-The SMESH python package contains (today) helper functions to
-manipulate mesh elements and interact with these elements.
-
-Note that these functions either encapsulate the python programming
-interface of SMESH core (the CORBA or SWIG interface for example) or
-extend existing utilities as the ``smesh.py`` module.
-
-The functions are distributed in the python package
-``salome.smesh``.
-
-The specification of the programming interface of this package is
-detailled in the part :doc:`Documentation of the programming interface
-(API)</docapi>` of this documentation.
-
-.. note::
-   The main package ``salome`` contains other sub-packages that are
-   distributed with the other SALOME modules. For example, the KERNEL
-   module provides the python package ``salome.kernel`` and GEOM the
-   package ``salome.geom``.
index ef2b284..380fb6b 100644 (file)
@@ -30,7 +30,7 @@ SET(kernel_file "${KERNEL_ROOT_DIR}/bin/salome/prepare_generating_doc.py")
 
 SALOME_ACCUMULATE_ENVIRONMENT(SMESH_MeshersList NOCHECK ${DOC_SMESH_MeshersList})
 
-SET(_cmd_options ${smesh_file} -d -o tmp/smeshBuilder.py StdMeshers)
+SET(_cmd_options ${smesh_file} -d -o tmp1/smeshBuilder.py StdMeshers)
 SALOME_GENERATE_ENVIRONMENT_SCRIPT(_cmd env_script "${PYTHON_EXECUTABLE}" "${_cmd_options}")            
 
 ADD_CUSTOM_TARGET(usr_docs ${CMAKE_COMMAND} -E make_directory tmp1
@@ -38,6 +38,7 @@ ADD_CUSTOM_TARGET(usr_docs ${CMAKE_COMMAND} -E make_directory tmp1
   COMMAND ${PYTHON_EXECUTABLE} ${kernel_file} -o tmp2/smeshBuilder.py ${CMAKE_SOURCE_DIR}/src/SMESH_SWIG/smeshBuilder.py
   COMMAND ${PYTHON_EXECUTABLE} ${kernel_file} -o tmp2/smesh_algorithm.py ${CMAKE_SOURCE_DIR}/src/SMESH_SWIG/smesh_algorithm.py
   COMMAND ${PYTHON_EXECUTABLE} ${kernel_file} -o tmp2/StdMeshersBuilder.py ${CMAKE_SOURCE_DIR}/src/SMESH_SWIG/StdMeshersBuilder.py
+  COMMAND ${PYTHON_EXECUTABLE} ${kernel_file} -o tmp2/smeshstudytools.py ${CMAKE_SOURCE_DIR}/src/SMESH_PY/smeshstudytools.py
   COMMAND ${_cmd}
   COMMAND ${DOXYGEN_EXECUTABLE} doxyfile_py
   COMMAND ${DOXYGEN_EXECUTABLE} doxyfile
index 1e2a17d..da7bdc7 100755 (executable)
@@ -102,6 +102,7 @@ EXAMPLE_RECURSIVE      = NO
 INPUT             = tmp2/smeshBuilder.py \
                     tmp2/smesh_algorithm.py \
                     tmp2/StdMeshersBuilder.py \
+                    tmp2/smeshstudytools.py \
                     tmp1/smeshBuilder.py
 FILE_PATTERNS     = 
 IMAGE_PATH        = @CMAKE_CURRENT_SOURCE_DIR@/images
index b3334e4..a4c2a66 100644 (file)
@@ -30,8 +30,6 @@ Also, there is a possibility to \subpage arranging_study_objects_page "re-arrang
 Almost all mesh module functionalities are accessible via
 \subpage smeshpy_interface_page "Mesh module Python interface".
 
-Other functions are available in <a class="el" target="_new" href="../../tui/SMESH/docutils/index.html">salome.smesh python package</a>.
-
 \image html image7.jpg "Example of MESH module usage for engineering tasks"
 
 */
index c690fb7..c3bb2ae 100644 (file)
@@ -15,9 +15,24 @@ in the \ref smeshBuilder and \ref StdMeshersBuilder Python packages.
 \n You may have to modify your scripts generated with SALOME 6 or older versions.
 \n Please see \ref smesh_migration_page
 
+The SMESH python package contains helper functions to manipulate mesh elements and 
+interact with these elements.
+
+Note that these functions either encapsulate the python programming interface of SMESH core 
+(the CORBA or SWIG interface for example) or extend existing utilities as the smesh.py module.
+
+The functions are distributed in the python package \b salome.smesh.
+
+\note
+The main package \bsalome contains other sub-packages that are distributed with the other 
+SALOME modules. For example, the KERNEL module provides the python package \b salome.kernel 
+and GEOM the package \b salome.geom.
+
 Class \ref smeshBuilder.smeshBuilder "smeshBuilder" provides an interface to create and handle
 meshes. It can be used to create an empty mesh or to import mesh from the data file.
 
+Class \ref smeshstudytools.SMeshStudyTools "SMeshStudyTools" provides several methods to manipulate mesh objects in Salome study. 
+
 As soon as mesh is created, it is possible to manage it via its own
 methods, described in class \ref smeshBuilder.Mesh "Mesh" documentation.
 
index b5a0a3e..a043765 100644 (file)
 #
 # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
 #
+
+## \package smeshstudytools Python API to access SMESH objects in the study.
+
+## \defgroup smeshstudytools Accessing SMESH object in the study
+#  \{ 
+#  \details
+#  Module \b smeshstudytools provides a new class SMeshStudyTools to facilitate the
+#  use of mesh objects in Salome study.
+#  \}
+
 """
 This module provides a new class :class:`SMeshStudyTools` to facilitate the
 use of mesh objects in Salome study.
@@ -31,6 +41,15 @@ from salome.kernel.deprecation import is_called_by_sphinx
 if not is_called_by_sphinx():
   from salome.gui import helper
 
+## This class provides several methods to manipulate mesh objects in Salome
+#  study. The parameter \em studyEditor defines a \b StudyEditor
+#  object used to access the study. If \b None, the method returns a 
+#  \b StudyEditor object on the current study.
+#
+#  \b editor
+#  This instance attribute contains the underlying \b StudyEditor object. 
+#  It can be used to access the study but the attribute itself should not be modified.
+#  \ingroup smeshstudytools
 class SMeshStudyTools:
     """
     This class provides several methods to manipulate mesh objects in Salome
@@ -56,13 +75,18 @@ class SMeshStudyTools:
         self.editor = studyEditor
         self.smeshGui = None
 
+    ## This function updates the tools so that it works on the
+    #  specified study.
     def updateStudy(self, studyId=None):
         """
         This function updates the tools so that it works on the
         specified study.
         """
         self.editor = getStudyEditor(studyId)
-        
+
+    ## Get the mesh item owning the mesh group \em meshGroupItem.
+    #  \param  meshGroupItem (SObject) mesh group belonging to the searched mesh.
+    #  \return The SObject corresponding to the mesh, or None if it was not found.        
     def getMeshFromGroup(self, meshGroupItem):
         """
         Get the mesh item owning the mesh group `meshGroupItem`.
@@ -81,20 +105,22 @@ class SMeshStudyTools:
             meshItem = salome.ObjectToSObject(meshObj)
         return meshItem
 
-
+    ## Returns the MESH object currently selected in the active study.
     def getMeshObjectSelected(self):
-        '''
+        """
         Returns the MESH object currently selected in the active study.
-        '''
+        """
         sobject, entry = helper.getSObjectSelected()
         meshObject = self.getMeshObjectFromEntry(entry)
         return meshObject
 
+    ## Returns the MESH object associated to the specified entry,
+    #  (the entry is the identifier of an item in the objects browser).
     def getMeshObjectFromEntry(self, entry):
-        '''
+        """
         Returns the MESH object associated to the specified entry,
         (the entry is the identifier of an item in the objects browser).
-        '''
+        """
         if entry is None:
             return None
         import SMESH
@@ -103,12 +129,14 @@ class SMeshStudyTools:
 
         meshObject=smesh.IDToObject(entry)
         return meshObject
-
+    
+    ## Returns the SMESH object associated to the specified \em SObject,
+    #  (the SObject is an item in the objects browser).
     def getMeshObjectFromSObject(self, sobject):
-        '''
+        """
         Returns the SMESH object associated to the specified SObject,
         (the SObject is an item in the objects browser).
-        '''
+        """
         if sobject is None:
             return None
         
@@ -116,11 +144,13 @@ class SMeshStudyTools:
         meshObject = obj._narrow(SMESH.SMESH_Mesh)
         return meshObject
 
+    ## Display the SMESH object associated to the specified \em entry
+    #  (the entry is the identifier of an item in the objects browser).
     def displayMeshObjectFromEntry(self,entry):
-        '''
+        """
         Display the SMESH object associated to the specified entry
         (the entry is the identifier of an item in the objects browser).    
-        '''
+        """
         if self.smeshGui is None:
             self.smeshGui = salome.ImportComponentGUI("SMESH")