From d7d0fd87e0cceb57b0c5e32f0712842763c7437c Mon Sep 17 00:00:00 2001 From: mpa Date: Fri, 14 Mar 2014 09:37:50 +0400 Subject: [PATCH] 0021746: EDF 2135 GEOM: Unification of Python documentations --- doc/CMakeLists.txt | 1 - doc/docutils/CMakeLists.txt | 36 ---- doc/docutils/conf.py.in | 200 ------------------ doc/docutils/docapi.rst | 17 -- doc/docutils/index.rst | 10 - doc/docutils/overview.rst | 24 --- doc/salome/gui/SMESH/CMakeLists.txt | 3 +- doc/salome/gui/SMESH/doxyfile_py.in | 1 + doc/salome/gui/SMESH/input/index.doc | 2 - .../gui/SMESH/input/smeshpy_interface.doc | 15 ++ src/SMESH_PY/smeshstudytools.py | 52 ++++- 11 files changed, 59 insertions(+), 302 deletions(-) delete mode 100755 doc/docutils/CMakeLists.txt delete mode 100644 doc/docutils/conf.py.in delete mode 100644 doc/docutils/docapi.rst delete mode 100644 doc/docutils/index.rst delete mode 100644 doc/docutils/overview.rst diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index fc259fe06..27aa5730a 100755 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -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 index d9cc0e302..000000000 --- a/doc/docutils/CMakeLists.txt +++ /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 index e87a7a007..000000000 --- a/doc/docutils/conf.py.in +++ /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 -# " v 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/. -html_copy_source = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a 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 index b39c124dc..000000000 --- a/doc/docutils/docapi.rst +++ /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 index 4863e8288..000000000 --- a/doc/docutils/index.rst +++ /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 index ce82cc812..000000000 --- a/doc/docutils/overview.rst +++ /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)` 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``. diff --git a/doc/salome/gui/SMESH/CMakeLists.txt b/doc/salome/gui/SMESH/CMakeLists.txt index ef2b284f3..380fb6bbd 100644 --- a/doc/salome/gui/SMESH/CMakeLists.txt +++ b/doc/salome/gui/SMESH/CMakeLists.txt @@ -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 diff --git a/doc/salome/gui/SMESH/doxyfile_py.in b/doc/salome/gui/SMESH/doxyfile_py.in index 1e2a17d61..da7bdc731 100755 --- a/doc/salome/gui/SMESH/doxyfile_py.in +++ b/doc/salome/gui/SMESH/doxyfile_py.in @@ -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 diff --git a/doc/salome/gui/SMESH/input/index.doc b/doc/salome/gui/SMESH/input/index.doc index b3334e418..a4c2a66ab 100644 --- a/doc/salome/gui/SMESH/input/index.doc +++ b/doc/salome/gui/SMESH/input/index.doc @@ -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 salome.smesh python package. - \image html image7.jpg "Example of MESH module usage for engineering tasks" */ diff --git a/doc/salome/gui/SMESH/input/smeshpy_interface.doc b/doc/salome/gui/SMESH/input/smeshpy_interface.doc index c690fb7ef..c3bb2ae18 100644 --- a/doc/salome/gui/SMESH/input/smeshpy_interface.doc +++ b/doc/salome/gui/SMESH/input/smeshpy_interface.doc @@ -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. diff --git a/src/SMESH_PY/smeshstudytools.py b/src/SMESH_PY/smeshstudytools.py index b5a0a3e6d..a04376579 100644 --- a/src/SMESH_PY/smeshstudytools.py +++ b/src/SMESH_PY/smeshstudytools.py @@ -18,6 +18,16 @@ # # 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")