From f9bbb3f2b8eca6494fe6ffb1d71d012969352e8a Mon Sep 17 00:00:00 2001 From: mpa Date: Thu, 13 Mar 2014 14:35:43 +0400 Subject: [PATCH] 0021746: EDF 2135 GEOM: Unification of Python documentations --- INSTALL | 2 +- doc/CMakeLists.txt | 3 +- doc/docutils/CMakeLists.txt | 35 -- doc/docutils/archives/INSTALL.txt | 355 ------------ doc/docutils/archives/KERNEL_Services.txt | 305 ----------- doc/docutils/archives/SALOME_Application.txt | 353 ------------ doc/docutils/archives/UnitTests.txt | 213 -------- doc/docutils/archives/index.txt | 113 ---- doc/docutils/archives/kernel_resources.txt | 507 ------------------ doc/docutils/archives/rst.css | 288 ---------- doc/docutils/archives/txt2html.sh | 56 -- doc/docutils/archives/userguide.txt | 141 ----- doc/docutils/conf.py.in | 200 ------- doc/docutils/docapi.rst | 14 - doc/docutils/index.rst | 22 - doc/docutils/kernel.rst | 81 --- doc/docutils/overview.rst | 47 -- doc/docutils/parametric.rst | 22 - doc/docutils/salomepypkg.rst | 271 ---------- doc/salome/gui/CMakeLists.txt | 34 +- doc/salome/gui/doxyfile.in | 4 +- doc/salome/main.dox | 3 +- doc/salome/python_doc_api.dox | 27 + doc/salome/python_doc_compl.dox | 214 ++++++++ doc/salome/python_doc_generale.dox | 45 ++ doc/salome/python_documentation.dox | 7 + src/KERNEL_PY/kernel/__init__.py | 16 + src/KERNEL_PY/kernel/datamodeler.py | 24 + src/KERNEL_PY/kernel/deprecation.py | 34 ++ src/KERNEL_PY/kernel/diclookup.py | 16 + src/KERNEL_PY/kernel/enumerate.py | 23 + src/KERNEL_PY/kernel/logger.py | 69 ++- src/KERNEL_PY/kernel/parametric/__init__.py | 7 + .../kernel/parametric/compo_utils.py | 40 ++ .../kernel/parametric/pyscript_utils.py | 41 ++ .../kernel/parametric/study_exchange_vars.py | 66 ++- src/KERNEL_PY/kernel/pyunittester.py | 17 +- src/KERNEL_PY/kernel/services.py | 50 +- src/KERNEL_PY/kernel/studyedit.py | 142 +++++ src/KERNEL_PY/kernel/termcolor.py | 91 +++- src/KERNEL_PY/kernel/uiexception.py | 15 + src/KERNEL_PY/kernel/unittester.py | 16 + 42 files changed, 973 insertions(+), 3056 deletions(-) delete mode 100755 doc/docutils/CMakeLists.txt delete mode 100644 doc/docutils/archives/INSTALL.txt delete mode 100644 doc/docutils/archives/KERNEL_Services.txt delete mode 100644 doc/docutils/archives/SALOME_Application.txt delete mode 100644 doc/docutils/archives/UnitTests.txt delete mode 100644 doc/docutils/archives/index.txt delete mode 100644 doc/docutils/archives/kernel_resources.txt delete mode 100644 doc/docutils/archives/rst.css delete mode 100755 doc/docutils/archives/txt2html.sh delete mode 100644 doc/docutils/archives/userguide.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/kernel.rst delete mode 100644 doc/docutils/overview.rst delete mode 100644 doc/docutils/parametric.rst delete mode 100644 doc/docutils/salomepypkg.rst create mode 100644 doc/salome/python_doc_api.dox create mode 100644 doc/salome/python_doc_compl.dox create mode 100644 doc/salome/python_doc_generale.dox create mode 100644 doc/salome/python_documentation.dox diff --git a/INSTALL b/INSTALL index e39fb5942..52d0fbd4f 100644 --- a/INSTALL +++ b/INSTALL @@ -1 +1 @@ -See ./doc/INSTALL.txt for installation instructions. \ No newline at end of file +SALOME : KERNEL module \ No newline at end of file diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 83a27c9f5..1cdfd614d 100755 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -17,5 +17,4 @@ # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com # -ADD_SUBDIRECTORY(salome) -ADD_SUBDIRECTORY(docutils) \ No newline at end of file +ADD_SUBDIRECTORY(salome) \ No newline at end of file diff --git a/doc/docutils/CMakeLists.txt b/doc/docutils/CMakeLists.txt deleted file mode 100755 index 1015880b9..000000000 --- a/doc/docutils/CMakeLists.txt +++ /dev/null @@ -1,35 +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/KERNEL) -INSTALL(FILES ${PROJECT_SOURCE_DIR}/doc/salome/tui/images/head.png DESTINATION ${SALOME_INSTALL_DOC}/tui/KERNEL) - -SET(MAKE_CLEAN_FILES docutils doctrees) -SET_DIRECTORY_PROPERTIES(PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES "${MAKE_CLEAN_FILES}") diff --git a/doc/docutils/archives/INSTALL.txt b/doc/docutils/archives/INSTALL.txt deleted file mode 100644 index 73769774d..000000000 --- a/doc/docutils/archives/INSTALL.txt +++ /dev/null @@ -1,355 +0,0 @@ -================================================================= -Installation instructions, up to date for 3.0 version -================================================================= - -*html version of this document is produced with docutils*:: - - rst2html < doc.txt > doc.html - -*This document corresponds to SALOME2 2.2.9.* -*IT IS NOT UP TO DATE with 3.2.0* - -.. contents:: -.. sectnum:: - -+-------------------------------------------+ -| **WORK in PROGRESS, INCOMPLETE DOCUMENT** | -+-------------------------------------------+ - -------------------------------------------------------------------------------- - -You'll find here generic instructions for installing the SALOME2 platform. - -Summary -------- - -`1. Quick Overview`_ - -`2. System configuration`_ - -`3. Third-party dependencies`_ - -`4. Preparing the shell environment`_ - -`5. Installing the KERNEL component`_ - -`6. Installing the SALOME components`_ - -`7. Runtime`_ - -`8. Suggestions and advices`_ - - -1. Quick Overview ------------------ - -First of all, you have to check (or install if needed) the dependant -software programs on your system. These programs are: - -- common development tools as gcc, CMake tool. -- third party softwares used in SALOME building or runtime process - (python, OCC, VTK, ...) - -Further details can be found in sections [2] and [3]. - -If the dependencies are installed on your system, then you have to set -your shell environment to get access to the software components -(cf. [4]. "Preparing the shell environment"). - -The next step is to install the KERNEL (cf. [5] "Installing KERNEL"): - -:: - -$ mkdir -$ mkdir -$ cd -$ cmake -DCMAKE_BUILD_TYPE= -DCMAKE_INSTALL_PREFIX= ../ -$ make -$ make install - -Where is build mode(Release or Debug), -is a destination folder to install KERNEL module of SALOME. - -Then, the SALOME components GEOM, MED, VISU, ... can be installed -with a similar procedure (cf. [6]). - -Eventually, the platform can be run by executing the shell script -runSalome (cf. [7]). Here, somme additionnal variables have to be set -to describe the SALOME runtime configuration (_ROOT_DIR, -OMNIORB_CONFIG) - -The following provides you with specific instructions for each step. - - -2. System configuration ------------------------ - -SALOME is compiled and tested on differents platforms with native packages: -- Debian sarge -- Mandrake 10.1 -- ... - -If you have another platform, we suggest the following configuration -for building process: - -- gcc-3.3.x or 3.4.x -- CMake-2.8.8 or more - -remarks: - -- This is the minimum level of CMake, if you need - to compile all the third party softwares (included OpenCascade 5.2.x). - -3. Third-party dependencies ---------------------------- - -The SALOME platform relies on a set of third-party softwares. The -current version depends on the following list -(versions given here are from Debian Sarge, except OpenCascade, VTK and MED, -which are not Debian packages): - -CAS-5.2.4 OpenCascade (try binaries,a source patch is needed) -VTK-4.2.6 VTK 3D-viewer -PyQt-3.13 Python-Qt Wrapper -Python-2.3.5 Python interpreter -SWIG-1.3.24 SWIG library -boost-1_32_0 C++ library (only include templates are used) -hdf5-1.6.2 Files Database library -med-2.2.2 MED Data Format support for file records -omniORB-4.0.5 ORB used in SALOME -qt-x11-free-3.3.3 Qt library -qwt-4.2 Graph components for Qt -sip4-4.1.1 langage binding software - -And, in order to build the documentation: - -doxygen-1.4.2 -graphviz-2.2.1 - - -Additionnal software may be installed for optional features: - -netgen4.3 + patch -tix8.1.4 -openpbs-2.3.16 -lsf-??? - - - -3.1 To Do -~~~~~~~~~ -- Instructions for installing these software programs can be found in a - special note doc/configuration_examples/install-prerequis. -- Installation shell scripts are also provided. - These scripts have to be adapted to your own configuration. - -- See doc/configuration_examples/* - -In the following, we assume that all the third-party softwares are -installed in the same root directory, named /prerequis. -Then, your file system should probably look like:: - - /prerequis/Python-2.2.2 - /prerequis/omniORB-3.0.5 - /prerequis/qt-x11-free-3.0.5 - ... - - -4. Preparing the shell environment ----------------------------------- - -Some variables have to be set to get acces to third-party software -components (include files, executable, library, ...) during building -process and runtime. - -The shell file prerequis.sh, embedded in the KERNEL source package, -provides a template for setting those variables. In this example, all the -softwares are supposed to be installed in the same root directory, -named here INSTALLROOT. - -Copy the prerequis.sh in a working directory and adjust the settings -to your own configuration. To get the shell prepared, just -execute the following command in the building shell: - -$ source prerequis.sh - -(we assume here a ksh or bash mode) - - -5. Installing the KERNEL component ----------------------------------- - -We use here the notation to specify the source directory -of the KERNEL component. The shell environment is supposed to have -been set (cf. 4). - -Installing the KERNEL from a source package needs three directories: - -- the source directory, denoted here by . - -- the build directory, denoted by in the following. This - directory can't be the same directory as . - -- the install directory, denoted by in the following. This - directory can't be the same directory as or - . - -The installing process is: - -STEP 1: - preparing directories - - create the and the directories:: - - $ mkdir - $ mkdir - -STEP 2: - go to build directory - - $ cd - -STEP 3: - configure the building process - $ cmake -DCMAKE_BUILD_TYPE= -DCMAKE_INSTALL_PREFIX= ../ - - Where is build mode(Release or Debug), - is a destination folder to install KERNEL module of SALOME. - Note that must be an absolute path. - - When the configure process is complete, check the status of cmake build. - You should not have the errors and warnings. All included products and packages must be found. - - If a software get a status "not found", then it's not "seen" in the system: - -- the software is not installed, or -- the shell environment is not set correctly. - -STEP 4 : - Building the binary files - - Execute make in the directory:: - - $ make - - -STEP 5: - Installing binary files, scripts and documentation - - Execute install target in the directory:: - - $ make install - - -6. Installing the SALOME components ------------------------------------ - -TInstalling a component is done by following the same -instructions as given for the KERNEL, replacing KERNEL by -. - -You just have to be aware of the dependencies between components: - -- MED depends on KERNEL -- GEOM depends on KERNEL -- SMESH depends on KERNEL, MED, GEOM -- VISU depends on KERNEL, MED -- SUPERV depends on KERNEL - -For example, installing the component SMESH needs the previous -installation of the KERNEL component, and then the GEOM and MED components. - -The building process uses the variables _ROOT_DIR to -localize the dependant components. The variables must be set to the -install path directory of the components (ex: -KERNEL_ROOT_DIR=). - -In the above example, the three variables KERNEL_ROOT_DIR, -GEOM_ROOT_DIR and MED_ROOT_DIR have to be set before configuring the -building process of the SMESH component (STEP 3). - - -7. Runtime ----------- - -See SALOME_Application_ to define your own configuration of SALOME and run it -on one or several computers. This is the recommended way of configuration. - -.. _SALOME_Application: ./SALOME_Application.html - -The following explains the general principles. - -To run the SALOME platform, the procedure is: - -- set the shell environment to get acces to third-party softwares:: - - $ source prerequis.sh - -- define the SALOME configuration by setting the whole set of - variables _ROOT_DIR. Here, you just have to set the - kernel and the components you need:: - - $ export KERNEL_ROOT_DIR= - $ export MED_ROOT_DIR= - $ ... - -- define the CORBA configuration file by setting the variable - OMNIORB_CONFIG. This variable must be set to a writable file - path. The file may be arbitrary chosen and doesn't need to exist - before running. We suggest:: - - $ export OMNIORB_CONFIG=$HOME/.omniORB.cfg - -- run the SALOME platform by executing the script runSalome:: - - $KERNEL_ROOT_DIR/bin/salome/runSalome - - -8. Suggestions and advices --------------------------- - -For convenience or customization, we suggest the following organisation: - -- chose and create a root directory for the SALOME platform, say - . - -- install the third-party softwares in a sub-directory "prerequis" - -- install the SALOME components in a sub-directory "SALOME2" - -- make personnal copies of the files prerequis.sh and runSalome in - :: - - $ cp /prerequis.sh /. - $ cp /bin/salome/runSalome /. - - Edit the file prerequis.sh and adjust it to your own configuration. - -- define the SALOME2 configuration - - This step consists in setting the KERNEL_ROOT_DIR, the whole set of - variables _ROOT_DIR you need, and the OMNIORB_CONFIG - variable. - - We suggest to create a shell file envSalome.sh containing those - settings. Then the configuration consists in loading envSalome.sh in - the runtime shell:: - - $ source envSalome.sh - -- When installed with this file organisation, running SALOME is done - with the following shell commands:: - - $ source /prerequis.sh - $ source /envSalome.sh - $ ./runSalome - - -------------------------------------------------------------------------------- - -+----------------------------------+------------------------------------------+ -| `General KERNEL documentation`_ | `End User KERNEL Doxygen documentation`_ | -+----------------------------------+------------------------------------------+ - -.. _`General KERNEL documentation`: ./index.html -.. _`End User KERNEL Doxygen documentation`: ./tui/KERNEL/index.html diff --git a/doc/docutils/archives/KERNEL_Services.txt b/doc/docutils/archives/KERNEL_Services.txt deleted file mode 100644 index 51bbf9da8..000000000 --- a/doc/docutils/archives/KERNEL_Services.txt +++ /dev/null @@ -1,305 +0,0 @@ -================================================================= -KERNEL Services for end user (Python interface) -================================================================= - -*html version of this document is produced with docutils*:: - - rst2html < doc.txt > doc.html - -This document corresponds to SALOME2 3.2.0 - -.. contents:: -.. sectnum:: - -+-------------------------------------------+ -| **WORK in PROGRESS, INCOMPLETE DOCUMENT** | -+-------------------------------------------+ - -------------------------------------------------------------------------------- - -In a SALOME application, distributed components, servers and clients use -the CORBA middleware for communication. CORBA interfaces are defined via idl -files. All the different CORBA interfaces are available for users in Python, -see CORBA interfaces below. - -For some general purpose services, CORBA interfaces have been encapsulated -in order to provide a simple interface (encapsulation is generally done in -C++ classes, and a Python SWIG interface is also generated from C++, to -ensure a consistent behavior between C++ modules and Python modules or user -script). - -General purpose services -======================== - -SALOME services access from a Python shell ------------------------------------------- -See SALOME_Application_ for detailed instructions to launch a Python -interpreter with full acces to the SALOME environment and services. - -.. _SALOME_Application: ./SALOME_Application.txt - -You can use the embedded Python interpreter in Grahic User Interface, or an -external interpreter, with:: - - ./runSession - python - -In either cases, SALOME services access is done with:: - - import salome - salome.salome_init() - -In the embedded interpreter, it is already done, but there is no problem to -do it several times, so it is preferable to add these instructions -systematically in your scripts, to allow them to work in all configurations. - -Container and component instantiation -------------------------------------- - -See LifeCycleCORBA_ for the C++ interface (Python interface obtained with SWIG -is very similar). - -.. _LifeCycleCORBA: ./tui/KERNEL/classSALOME__LifeCycleCORBA.html - - -In the following example, a test component provided in KERNEL is launched -in the local container, "FactoryServer", created when SALOME starts:: - - import salome - salome.salome_init() - - import LifeCycleCORBA - lcc = LifeCycleCORBA.LifeCycleCORBA() - obj=lcc.FindOrLoad_Component("FactoryServer","SalomeTestComponent") - - import Engines - comp=obj._narrow(Engines.TestComponent) - - comp.Coucou(1) - -The answer is something like:: - - 'TestComponent_i : L = 1' - -The _narrow() instruction is not always mandatory in Python, but sometimes -useful to be sure you have got the right type of object. Here, Testcomponent_ -interface is defined in CORBA module Engines. With this example, it works also -without the _narrow() instruction:: - - obj.Coucou(1) - -.. _Testcomponent: ./tui/KERNEL/interfaceEngines_1_1TestComponent.html - - -In the next example, a component instance is created in a specific Container -defined by it's computer hostname and it's name. Here we use the local -computer. Note that in Utils_Identity_, getShortHostName() gives the short -hostname of the computer, without domain suffixes, which is used in SALOME. -The container process is created here if it does not exists, and a new -component instance is created:: - - import salome - salome.salome_init() - import LifeCycleCORBA - lcc = LifeCycleCORBA.LifeCycleCORBA() - - import Utils_Identity - host = Utils_Identity.getShortHostName() - - import Engines - params={} - params['hostname']=host - params['container_name']='myContainer' - comp=lcc.LoadComponent(params,'SalomeTestComponent') - comp.Coucou(1) - -.. _Utils_Identity: ./tui/KERNEL/namespaceUtils__Identity.html - -If you want to get a list of containers and component instances, client object -from orbmodule_ provides a list:: - - import orbmodule - clt=orbmodule.client() - clt.showNS() - -.. _orbmodule: ./tui/KERNEL/classorbmodule_1_1client.html - -The list looks like:: - - Logger. - ContainerManager.object - Containers.dir - cli70ac.dir - FactoryServerPy.object - SuperVisionContainer.object - FactoryServer.object - FactoryServer.dir - SalomeTestComponent_inst_1.object - myContainer.object - myContainer.dir - SalomeTestComponent_inst_1.object - SalomeTestComponent_inst_2.object - Registry.object - Kernel.dir - ModulCatalog.object - Session.object - Study.dir - Study2.object - extStudy_1.object - extStudy_2.object - extStudy_3.object - myStudyManager.object - SalomeAppEngine.object - - -File transfer service ---------------------- - -See FileTransferCORBA_ for the C++ interface (Python interface obtained with -SWIG is very similar). - -.. _FileTransferCORBA: ./tui/KERNEL/classSALOME__FileTransferCORBA.html - -The following example shows how to tranfer a file from a remote host to the -client computer. Remote hostname is 'cli76cc', we would like to copy -'tkcvs_8_0_3.tar.gz' from remote to local computer. A full pathname is -required. A container is created on remote computer if it does not exist, -to handle the file transfer:: - - import salome - salome.salome_init() - - import LifeCycleCORBA - remotefile="/home/prascle/tkcvs_8_0_3.tar.gz" - aFileTransfer=LifeCycleCORBA.SALOME_FileTransferCORBA('cli76cc',remotefile) - localFile=aFileTransfer.getLocalFile() - - -CORBA Naming service access ---------------------------- - -See SALOME_NamingService_ for the C++ interface. The Python interface -SALOME_NamingServicePy_ is not yet derived from the C++ interface and offers -only the most useful functions. - -.. _SALOME_NamingService: ./tui/KERNEL/classSALOME__NamingService.html -.. _SALOME_NamingServicePy: ./tui/KERNEL/classSALOME__NamingServicePy_1_1SALOME__NamingServicePy__i.html - -Batch services --------------- - -See Batch_ documentation (in french only). - -.. _Batch: ./Batch.html/index.html - -All IDL Interfaces -================== - -Containers and component life cycle, File transfer service ----------------------------------------------------------- - -+-----------------------------+-----------------------------------------------+ -| Engines_ | Engines CORBA module. | -+=============================+===============================================+ -| Component_ | Generic component interface. | -| | All SALOME components inherit this interface | -+-----------------------------+-----------------------------------------------+ -| Container_ | Container: host for C++ and Python components | -| | components instances | -+-----------------------------+-----------------------------------------------+ -| FileTransfer_ | Agent for file transfer created by a container| -| | copy a local file to a distent client | -+-----------------------------+-----------------------------------------------+ -| FileRef_ | Reference to a file, used by a container for | -| | file transfers | -+-----------------------------+-----------------------------------------------+ -| ContainerManager_ | Unique instance, in charge of container | -| | creation on remote computers | -+-----------------------------+-----------------------------------------------+ -| MPIContainer_ | An exemple of parallel implementation for | -| | containers and components | -+-----------------------------+-----------------------------------------------+ -| MPIObject_ | | -+-----------------------------+-----------------------------------------------+ - -Study management ----------------- - -+-----------------------------+-----------------------------------------------+ -| SALOMEDS_ | SALOMEDS CORBA module | -+=============================+===============================================+ -| SALOMEDSidl_ | | -+-----------------------------+-----------------------------------------------+ -| SALOMEDS_Attributes_ | | -+-----------------------------+-----------------------------------------------+ - -High speed transfer, object life cycle, exceptions, GUI interface... --------------------------------------------------------------------- - -+-----------------------------+-----------------------------------------------+ -| SALOME_ | SALOME CORBA module | -+=============================+===============================================+ -| SALOME_Comm_ | | -+-----------------------------+-----------------------------------------------+ -| SALOME_GenericObj_ | | -+-----------------------------+-----------------------------------------------+ -| SALOME_Exception_ | | -+-----------------------------+-----------------------------------------------+ -| SALOME_Session_ | | -+-----------------------------+-----------------------------------------------+ - -Miscelleanous -------------- -+-----------------------------+-----------------------------------------------+ -| | other CORBA modules | -+=============================+===============================================+ -| SALOME_ModuleCatalog_ | | -+-----------------------------+-----------------------------------------------+ -| SALOME_RessourcesCatalog_ | | -+-----------------------------+-----------------------------------------------+ -| SALOME_Registry_ | | -+-----------------------------+-----------------------------------------------+ -| Logger_ | | -+-----------------------------+-----------------------------------------------+ - -**Other idl for test purposes** -nstest.idl -SALOME_TestComponent.idl -SALOME_TestModuleCatalog.idl -SALOME_TestMPIComponent.idl -TestNotif.idl - -.. _Engines: ./tui/KERNEL/namespaceEngines.html -.. _Component: ./tui/KERNEL/interfaceEngines_1_1Component.html -.. _Container: ./tui/KERNEL/interfaceEngines_1_1Container.html -.. _fileTransfer: ./tui/KERNEL/interfaceEngines_1_1fileTransfer.html -.. _fileRef: ./tui/KERNEL/interfaceEngines_1_1fileRef.html -.. _ContainerManager: ./tui/KERNEL/interfaceEngines_1_1ContainerManager.html -.. _MPIContainer: ./tui/KERNEL/interfaceEngines_1_1MPIContainer.html -.. _MPIObject: ./tui/KERNEL/interfaceEngines_1_1MPIObject.html -.. _SALOME: ./tui/KERNEL/namespaceSALOME.html -.. _SALOMEDS: ./tui/KERNEL/namespaceSALOMEDS.html -.. _SALOME_Component: ./tui/KERNEL/SALOME__Component_8idl.html -.. _SALOME_ContainerManager: ./tui/KERNEL/SALOME__ContainerManager_8idl.html -.. _SALOMEDSidl: ./tui/KERNEL/SALOMEDS_8idl.html -.. _SALOMEDS_Attributes: ./tui/KERNEL/SALOMEDS__Attributes_8idl.html -.. _SALOME_ModuleCatalog: ./tui/KERNEL/SALOME__ModuleCatalog_8idl.html -.. _SALOME_RessourcesCatalog: ./tui/KERNEL/SALOME__RessourcesCatalog_8idl.html -.. _SALOME_Registry: ./tui/KERNEL/SALOME__Registry_8idl.html -.. _Logger: ./tui/KERNEL/Logger_8idl.html -.. _SALOME_Comm: ./tui/KERNEL/SALOME__Comm_8idl.html -.. _SALOME_GenericObj: ./tui/KERNEL/SALOME__GenericObj_8idl.html -.. _SALOME_Exception: ./tui/KERNEL/SALOME__Exception_8idl.html -.. _SALOME_Session: ./tui/KERNEL/SALOME__Session_8idl.html -.. _SALOME_MPIContainer: ./tui/KERNEL/SALOME__MPIContainer_8idl.html -.. _SALOME_MPIObject: ./tui/KERNEL/SALOME__MPIObject_8idl.html - - -------------------------------------------------------------------------------- - -+----------------------------------+------------------------------------------+ -| `General KERNEL documentation`_ | `End User KERNEL Doxygen documentation`_ | -+----------------------------------+------------------------------------------+ - -.. _`General KERNEL documentation`: ./index.html -.. _`End User KERNEL Doxygen documentation`: ./tui/KERNEL/index.html diff --git a/doc/docutils/archives/SALOME_Application.txt b/doc/docutils/archives/SALOME_Application.txt deleted file mode 100644 index c77bd6da2..000000000 --- a/doc/docutils/archives/SALOME_Application.txt +++ /dev/null @@ -1,353 +0,0 @@ -====================================================================== -SALOME Application Concept. Configuration for one or more computers -====================================================================== - -*html version of this document is produced with docutils*:: - - rst2html doc.txt > doc.html - -This document corresponds to SALOME2 3.2.0 - -.. contents:: -.. sectnum:: - -+-------------------------------------------+ -| **WORK in PROGRESS, INCOMPLETE DOCUMENT** | -+-------------------------------------------+ - -------------------------------------------------------------------------------- - -The following explains how to configure your own application with your list of -modules, how to define and run this application on one or more computers. - -General principles ------------------- - -A SALOME application is defined by a set of modules (GEOM, SMESH, ASTER...). - -A SALOME User can define several SALOME Applications. These applications are -runnable from the same user account. These applications may share the same -KERNEL and modules. Thus, the application configuration is independant of -KERNEL and must not be put in KERNEL_ROOT_DIR. - -Furthermore, prerequisites may not be the same on all the applications. - -A SALOME Session can run on a several computers. - -Binary modules and prerequisites are installed on the different computers. -There is no need to have all the modules on each computer (the minimum is -KERNEL). - -There is no need of standardization or centralised information on the details -of configuration on each computer (PATH, LD_LIBRARY_PATH, environment -variables) provided the application modules are version - compatible. Details -of configuration stay private to the computer, and are held by scripts on each -computer. - -There is no hierarchy between the computers (for example only one master -computer used to launch application). - -The SALOME user has an account on all the computers. Access between -account@computer is via rsh or ssh and must be configured for use without -password (key exchange for ssh). Account may be different on each -computer. - -Application Directory ---------------------- - -Two ways for creation of an application directory -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -First way - references to different module directories -'''''''''''''''''''''''''''''''''''''''''''''''''''''' - -The script createAppli.sh in ${KERNEL_ROOT_DIR}/bin/salome creates an -application directory with the given path in parameter. ${APPLI} is a path -relative to ${HOME}. - -The directory is only a skeleton, the user has to edit several files to -configure his own application. These files are described after, the list is: - -- env.d/atFirst.sh -- env.d/envProducts.sh -- env.d/envSalome.sh -- CatalogResources.xml -- SalomeApp.xml - -Second and easiest way - one single virtual install directory -''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' - -The user must create a SALOME application configuration file by modifying a -copy of ${KERNEL_ROOT_DIR}/bin/salome/config_appli.xml. -The file describes the list of SALOME modules used in the application, with -their respective installation path. The configuration file also defines the -path of an existing script which sets the SALOME prerequisites, -and optionnaly, the path of samples directory (SAMPLES_SRC). -The following command:: - - python /bin/salome/appli_gen.py --prefix= --config= - -creates a virtual installation of SALOME in the application directory ${APPLI} -(bin, lib, doc, share...), with, for each file (executable, script, data, -library, resources...), symbolic links to the actual file. - -Providing an existing script for SALOME prerequisites (the same one -used for modules compilation, or given with the modules installation), the -installation works without further modification for a single computer (unless -some modules needs a special environment not defined in the above script). -For a distributed application (several computers), one must copy and adapt -CatalogResources.xml from ${KERNEL_ROOT_DIR}/bin/salome/appliskel (see below). - -General rules -------------- - -Directory ${APPLI} must be created on each computer of the application. -The easiest way is to use the same relative path (to ${HOME}) on each computer. -(Sometimes it is not possible to use the same path everywhere, for instance -when ${HOME} is shared with NFS, so it is possible to define different path -following the computers). - -The ${APPLI} directory contains scripts for environment and runs. Environment -scripts must be configured (by the user) on each computer. All the environment -scripts are in the ${APPLI}/env.d directory. - -The script ${APPLI}/envd sources **all** the files (\*.sh) in ${APPLI}/env.d -in alphanumeric order (after edition, think to remove backup files). the envd -script is used by run scripts. - - -env.d scripts -~~~~~~~~~~~~~ -With the first way of installation, each user **must define** his own -configuration for these scripts, following the above rules. -With the virtual installation (second way, above), env.d -scripts are built automatically. - - **The following is only an example proposed by createAppli.sh, (first way of installation) not working as it is**. - -atFirst.sh - Sets the computer configuration not directly related to SALOME, - like useful tools, default PATH. - -envProducts.sh - Sets the SALOME prerequisites. - -envSALOME.sh - Sets all the MODULE_ROOT_DIR that can be used in the SALOME application. - - SalomeAppConfig is also defined by:: - - export SalomeAppConfig=${HOME}/${APPLI} - - where SalomeAppConfig designates the directory containing SalomeApp.xml. - Note that ${APPLI} is already defined by the calling scripts when - env.d/envSalome.sh is sourced. - -User run scripts -~~~~~~~~~~~~~~~~ - -The SALOME user can use 4 scripts: - -runAppli - Launches a SALOME Session - (similar to ${KERNEL_ROOT_DIR}/bin/salome/runSalome but with a different - name to avoid confusions). - -runSession - Launches a shell script in the SALOME application environment, with access - to the current (last launched) SALOME session (naming service), if any. - Without arguments, the script is interactive. With arguments, the script - executes the command in the SALOME application environment. - -runConsole - Gives a python console connected to the current SALOME Session. - It is also possible to use runSession, then python. - -runTests - Similar to runSession, used for unit testing. runSession tries to use an - already existing naming service definition from a running session (hostname - and port number), runTests defines a new configuration for naming service - (new port number). - -SALOME internal run scripts -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -envd - Sets SALOME application environment, envd is sourced by other scripts. - -For remote calls, SALOME uses one script. - -runRemote.sh - This script is mainly used to launch containers. The first 2 arguments - define the hostname and port userd for naming service, the remaining - arguments define the command to execute. - -Other configuration files -~~~~~~~~~~~~~~~~~~~~~~~~~ - -SalomeApp.xml - This file is similar to the default given - in ${GUI_ROOT_DIR}/share/salome/resources/gui - - -CatalogRessources.xml - This files describes all the computers the application can use. The given - example is minimal and suppose ${APPLI} is the same relative path - to ${HOME}, on all the computers. A different directory can be set on a - particular computer with a line:: - - appliPath="my/specific/path/on/this/computer" - - -Examples of use ---------------- - -Launch a SALOME session with a GUI interface -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Launch is done with a command like:: - - ./runAppli --logger - -The --logger option means here : collect all the traces from the all the -distributed process, via CORBA, in a single file : logger.log. - -There are a lot of options, a complete list is given by:: - - ./runAppli --help - -Note that, without argument, runAppli is a non interactive Python application, -and, with arguments, runAppli is an interactive Python interpreter. - -Several options are already defined by default in SalomeApp.xml files. Optional -arguments given in the command override the SalomeApp.xml configuration. - -Several sessions can run simultaneously, each session use a different port for -CORBA naming service, so the sessions are totally separated from each other. - -When the GUI is closed, the different SALOME servers are still running. - -Close a SALOME session, kill all the servers -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Inside the interactive python interpreter you get when you use runAppli -with arguments, you can kill all the servers of your session with:: - - >>> killLocalPort() - -or the servers of all the sessions with:: - - >>> killAllPorts() - -If you have no active Python interpreter connected to your session, you can -kill all the SALOME servers of **all the sessions** on a given computer:: - - ./runSession killSalome.py - -Remember! it's the same idea in *Windows (R) operating system* [#]_ : -use the start menu to stop... - -When you use only one session at a time, you don't need more. - -To kill a given session (when several session are running), one needs -the naming service port number:: - - ./runSession killSalomeWithPort 2810 - -Note that the port number of the last launched session can be found on Linux, -in the prompt, within a runSession shell (see below). - -It is also possible to get the Naming Service host and port number of -the last launched session with:: - - ./runSession NSparam.py - -.. [#] Microsoft and Windows are either registered trademarks or trademarks of - Microsoft Corporation in the United States and/or other countries. - -Launch a SALOME session without GUI interface -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This is used to launch a SALOME Python script without GUI -(no GUI server = SALOME_session_server) - -Example of script (test_session_geom.py):: - - import salome_session - salome_session.startSession(modules=["GEOM"]) - import GEOM_usinggeom - raw_input("Press a key and the servers will be killed ...") - -This script is run in a non interactive way with:: - - ./runSession python test_session_geom.py - -All the process are automatically killed when Python is closed -(with salome_session delete). - -Add an external Python interpretor to a running session -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -It's often easier to develop and try Python scripts outside the GUI embedded -Python interpreter. Imagine, for instance, you are writing a script involving -geometry and mesh modules. -First, launch a SALOME session with gui, then, on another terminal:: - - ./runSession - python - -Import salome module. salome_init() without arguments creates a new study -in the running session (note: salome_init(n) attachs to a running session whose -studyId is n):: - - import salome - salome.salome_init() - -An example of script given with SMESH:: - - import ex01_cube2build - -It is possible to connect the GUI interface to the study created in the above -script with the file/connect menu, then browse study and display objects. -Further modifications on study can be done either with GUI or external script -(use refresh popup in GUI object browser to see study modifications generated -by the external script). **AVOID modifications with GUI when a Python script -is running**. Not all the modules are protected against concurrent actions... - - -Different uses of the runSession shell interpreter -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -runSession invoked without arguments gives an interactive shell with the full -environment of SALOME (PATH, LD_LIBRARY_PATH, PYTHONPATH, other variables). -If there are running sessions of the same SALOME application, runSession -connects to the last launched session (i.e. gets the naming service references -of the session: hostname and port) - -On Linux, the shell prompt (bash) gives information on naming service -references, hostname and port:: - - [NS=cli76cc:2811]prascle@cli76cc:~/SALOME2/Run/Virtual$ - -If there is no running session, prompt looks like:: - - [NS=:]prascle@cli76cc:~/SALOME2/Run/Virtual$ - -runSession is useful to launch any script or program which needs the complete -SALOME environment, with or without a session already running. -For instance, to launch the ddd debugger interface on the gui server, first -launch a SALOME session with gui, then, on another terminal:: - - ./runSession ddd - -Then attach to the running SALOME_Session_Server process. - - -------------------------------------------------------------------------------- - -+----------------------------------+------------------------------------------+ -| `General KERNEL documentation`_ | `End User KERNEL Doxygen documentation`_ | -+----------------------------------+------------------------------------------+ - -.. _`General KERNEL documentation`: ./index.html -.. _`End User KERNEL Doxygen documentation`: ./tui/KERNEL/index.html diff --git a/doc/docutils/archives/UnitTests.txt b/doc/docutils/archives/UnitTests.txt deleted file mode 100644 index f30f38202..000000000 --- a/doc/docutils/archives/UnitTests.txt +++ /dev/null @@ -1,213 +0,0 @@ -================================================================= -Source code structuration and Unit Tests -================================================================= - -*html version of this document is produced with docutils*:: - - rst2html < doc.txt > doc.html - -*This document corresponds to SALOME2 3.2.0* - -.. contents:: -.. sectnum:: - -+-------------------------------------------+ -| **WORK in PROGRESS, INCOMPLETE DOCUMENT** | -+-------------------------------------------+ - -------------------------------------------------------------------------------- - -You will find here general information on code directories structure, -unit tests associated to the different kind of classes, and how to run -the unit tests. - -SALOME KERNEL source code structuration -======================================= - -General structure of KERNEL_SRC -------------------------------- - -KERNEL_SRC - Some README files and configuration tools for build - -KERNEL_SRC/bin - Python and shell scripts used at run time. - Kit to install a SALOME Application. - -KERNEL_SRC/doc - Kit for KERNEL end user documentation production: - public interfaces, Python, CORBA. - Integrator and Developper documentation. - -KERNEL_SRC/idl - All CORBA interfaces from KERNEL are regrouped here. - -KERNEL_SRC/resources - Configuration files for servers (examples). - Interfaces definitions for KERNEL test components. - -KERNEL_SRC/salome_adm - Configuration files used by autotools (M4 macros & co.) - -KERNEL_SRC/src - The source code (C++ and Python) - - -Directory src: C++ and Python source code ------------------------------------------ - -Basic services non related to CORBA -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Basics - A set of general purpose C++ services, not related to CORBA. - Some general purpose services that are in Utils directory (CORBA related), - are progressivley moved here, as they are not related to CORBA. - - -SALOMELocalTrace - A multithread trace system that allows message tracing on standard error - or a file. - -CASCatch - Exceptions and signal handler. - -HDFPersist - A C++ interface to HDF. - -Basic CORBA services -~~~~~~~~~~~~~~~~~~~~ - -Logger - A CORBA server that collects the trace messages from differents CORBA - process. - -SALOMETraceCollector - A multithread trace system derived from SALOMELocalTrace, that sends messages - to Logger server via CORBA. - -Utils - A set of general purpose services related to CORBA, such as basic CORBA - exception system. See also Basics directory above. - -NamingService - C++ and Python interfaces to name, store and retrieve CORBA objects - -GenericObj - A generic CORBA interface for CORBA objects, to count distributed references, - and to allow destruction by client. - -Miscellaneous CORBA servers -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Registry - Implements SALOME_registry.idl. - Provides a CORBA server library and a separate server program. - -ModuleCatalog - Implements SALOME_moduleCatalog.idl. - Provide a CORBA server library and separate server and client programs. - -ModuleGenerator - Tool to generate a module catalog from CORBA idl - -ResourcesManager - library included in container server - -Notification - library included in differents servers (container) - -NOTIFICATION_SWIG - - -CORBA Containers for SALOME Modules -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Container - -TestContainer - -LifeCycleCORBA - -LifeCycleCORBA_SWIG - -STUDY server and related interfaces and tools -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -SALOMEDSClient - -TOOLSDS - -SALOMEDSImpl - -SALOMEDS - -Python interface to SALOME -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -KERNEL_PY - -Efficient CORBA transfer services -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Communication - -Communication_SWIG - -A Parallel container with MPI -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -MPIContainer - -TestMPIContainer - -Batch interface library -~~~~~~~~~~~~~~~~~~~~~~~ - -Batch - -Batch_SWIG - -Unit tests -~~~~~~~~~~ - -UnitTests - - -Tools and principles used for Unit testing -========================================== - -**TO BE COMPLETED** - -Unit Testing rely on cppunit package for C++ testing, and on unittest module -for Python. See these products for general principles of unit testing. - -The cppunit package is optional. When the prerequisite is detected, the unit -tests are compiled. - -Unit Tests sources are in directories Test under the src/directories -containing the classes to test. - -Test are ordered following the order of directories given above. - -Tests can be run as a whole, or for a particular directory. In this case, only -a partial test is run (the classes to test, and the classes used, i.e. the -preceding test directories). - - -Today, only some tests are written as an example. There are not yet python -scripts in KERNEL_SRC, but it's a matter of days, there are working scripts -to test LifeCycleCORBA_SWIG interface. - - - - - -------------------------------------------------------------------------------- - -+----------------------------------+------------------------------------------+ -| `General KERNEL documentation`_ | `End User KERNEL Doxygen documentation`_ | -+----------------------------------+------------------------------------------+ - -.. _`General KERNEL documentation`: ./index.html -.. _`End User KERNEL Doxygen documentation`: ./tui/KERNEL/index.html diff --git a/doc/docutils/archives/index.txt b/doc/docutils/archives/index.txt deleted file mode 100644 index 0120b1d9c..000000000 --- a/doc/docutils/archives/index.txt +++ /dev/null @@ -1,113 +0,0 @@ -================================================================= -KERNEL common Services -================================================================= - -*html version of this document is produced with docutils*:: - - rst2html < doc.txt > doc.html - -*This document corresponds to SALOME2 3.2.0* - -.. contents:: -.. sectnum:: - -+-------------------------------------------+ -| **WORK in PROGRESS, INCOMPLETE DOCUMENT** | -+-------------------------------------------+ - -------------------------------------------------------------------------------- - -**General information, for users, integrators and developers** - -**Users, integrators and developers, which documentation ?** - -Following your kind of usage of SALOME, you will find some specific -introductory documentation, listed below. - -End user -======== - -How to configure a SALOME application -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The end user may have to configure his own SALOME application by selection of a -subset of availables SALOME modules. He also may want to install his -application on several computers. - -See SALOME_Application_ to define your own configuration of SALOME and run it -on one or several computers. This is the recommended way of configuration. - -.. _SALOME_Application: ./SALOME_Application.html - - -How to launch SALOME in a SALOME application -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -See SALOME_Application_. - -How to use KERNEL services in Python scripts -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The SALOME KERNEL offers offers a list of services available in Python. - -See KERNEL_Services_. - -.. _KERNEL_Services: ./KERNEL_Services.html - -Application Integrator -====================== - -Applications integrators are in charge of configuration and installation of -specific SALOME applications over a local network. Application Integrators -built SALOME modules binaries from sources tarballs. - -How to install SALOME -~~~~~~~~~~~~~~~~~~~~~ - -See INSTALL_ for general information on required configuration and -prerequisites, compilation procedure, setting environment principles. - -.. _INSTALL: ./INSTALL.html - -How to configure a SALOME application -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -See SALOME_Application_ to define your own configuration of SALOME and run it -on one or several computers. This is the recommended way of configuration. - -.. _SALOME_Application: ./SALOME_Application.html - - -Module maintainer -================= - -Module maintainers are in charge of the development and debug of the SALOME -modules. Each SALOME module is stored in a CVS base. CVS bases are organised -in separate branches for developments and debug. All official or development -releases are identified by a CVS tag. - -Source code structuration and Unit Tests -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -See UnitTests_ for general information on code directories structure, -unit tests associated to the different kind of classes, and how to run -the unit tests. - -.. _UnitTests: ./UnitTests.html - -Some development utilities -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -See kernel_resources_ for information on basic utilities for C++ and Python -development, like trace and debug, exceptions, singleton. - -.. _kernel_resources: ./kernel_resources.html - -------------------------------------------------------------------------------- - -+----------------------------------+------------------------------------------+ -| `General KERNEL documentation`_ | `End User KERNEL Doxygen documentation`_ | -+----------------------------------+------------------------------------------+ - -.. _`General KERNEL documentation`: ./index.html -.. _`End User KERNEL Doxygen documentation`: ./tui/KERNEL/index.html diff --git a/doc/docutils/archives/kernel_resources.txt b/doc/docutils/archives/kernel_resources.txt deleted file mode 100644 index c3ca235ce..000000000 --- a/doc/docutils/archives/kernel_resources.txt +++ /dev/null @@ -1,507 +0,0 @@ -====================================================================== -SALOME Kernel resources for developer -====================================================================== - -*html version of this document is produced with docutils*:: - - rst2html doc.txt > doc.html - -*This document corresponds to SALOME2 3.2.0* - -:Authors: - Antoine Yessayan, - Paul Rascle - -:Version: 0.3 - february 17, 2006 - -+-------------------------------------------+ -| **WORK in PROGRESS, INCOMPLETE DOCUMENT** | -+-------------------------------------------+ - -------------------------------------------------------------------------------- - -**Abstract** - -This document describes the development environment for -C++ and Python. Makefiles generation and usage are -introduced in another document: "using the SALOME -configuration and building system environment". -Development environment is intended here as: trace and -debug macros usage; SALOME exceptions usage, in C++ and -Python; user CORBA exceptions usage, in C++ and Python, -with and without Graphical User Interface; some general -purpose services such as singleton, used for CORBA -connection and disconnection. - -.. contents:: -.. sectnum:: - -------------------------------------------------------------------------------- - -Trace and debug Utilities -========================= - -During the development process, an execution log is -useful to identify problems. This log contains -messages, variables values, source files names and line -numbers. It is recommended to verify assertions on -variables values and if necessary, to stop the -execution at debug time, in order to validate all parts -of code. - -Two modes: debug and release ----------------------------- - -The goal of debug mode is to check as many features as -possible during the early stages of the development -process. The purpose of the utilities provided in -SALOME is to help the developer to add detailed traces -and check variables values, without writing a lot of code. - -When the code is assumed to be valid, the release mode -optimizes execution, in terms of speed, memory, and -display only user level messages. - -But, some informations must always be displayed in both -modes: especially messages concerning environment or -internal errors, with version identification. When an -end user is confronted to such a message, he may refer -to a configuration documentation or send the message to -the people in charge of SALOME installation, or to the -development team, following the kind of error. - -C++ Macros for trace and debug ------------------------------- - -SALOME provides C++ macros for trace and debug. These -macros are in:: - - KERNEL_SRC/src/SALOMELocalTrace/utilities.h - -This file must be included in C++ source. Some -macros are activated only in debug mode, others are -always activated. To activate the debug mode, ``_DEBUG_`` -must be defined, which is the case when SALOME -Makefiles are generated from CMakeLists.txt, without -options. When ``_DEBUG_`` is undefined (release mode: -``cmake -DCMAKE_BUILD_TYPE=Release ../KERNEL_SRC``), the -debug mode macros are defined empty (they do nothing). -So, when switching from debug to release, it is -possible (and recommended) to let the macro calls -unchanged in the source. - -All the macros generate trace messages, stored in a -circular buffer pool. A separate thread reads the -messages in the buffer pool, and, depending on options -given at SALOME start, writes the messages on the -standard output, a file, or send them via CORBA, in -case of a multi machine configuration. - -Three informations are systematically added in front of -the information displayed: - -* the thread number from which the message come from; - -* the name of the source file in which the macros is set; - -* the line number of the source file at which the macro - is set. - -Macros defined in debug and release modes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**INFOS_COMPILATION** - The C++ macro INFOS_COMPILATION writes on the trace - buffer pool informations about the compiling process: - - * the name of the compiler : g++, KCC, CC, pgCC; - - * the date and the time of the compiling processing process. - - This macro INFOS_COMPILATION does not have any - argument. Moreover, it is defined in both compiling - mode : _DEBUG_ and _RELEASE_. - - Example:: - - #include "utilities.h" - int main(int argc , char **argv) - { - INFOS_COMPILATION; - ... - } - INFOS(str) - -**INFOS** - In both compiling mode _DEBUG_ and _RELEASE_, The C++ - macro INFOS writes on the trace buffer pool the string - which has been passed in argument by the user. - - Example:: - - #include "utilities.h" - int main(int argc , char **argv) - { - ... - INFOS("NORMAL END OF THE PROCESS"); - return 0; - } - - displays:: - - main.cxx [5] : NORMAL END OF THE PROCESS - - -**INTERRUPTION(str)** - In both compiling mode _DEBUG_ and _RELEASE_, The C++ - macro INTERRUPTION writes on the trace buffer pool the - string, with a special ABORT type. When the thread in - charge of collecting messages finds this message, it - terminates the application, after message treatment. - -**IMMEDIATE_ABORT(str)** - In both compiling mode _DEBUG_ and _RELEASE_, The C++ - macro IMMEDIATE_ABORT writes the message str immediately on - standard error and exits the application. Remaining - messages not treated by the message collector thread - are lost. - -Macros defined only in debug mode -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**MESSAGE(str)** - In _DEBUG_ compiling mode only, the C++ macro MESSAGE - writes on the trace buffer pool the string which has - been passed in argument by the user. In _RELEASE_ - compiling mode, this macro is blank. - - Example:: - - #include "utilities.h" - #include - - using namespace std; - - int main(int argc , char **argv) - { - ... - const char *str = "Salome"; - MESSAGE(str); - ... const string st; - st = "Aster"; - MESSAGE(c_str(st+" and CASTEM")); - return 0; - } - - displays:: - - - Trace main.cxx [8] : Salome - - Trace main.cxx [12] : Aster and CASTEM - -**BEGIN_OF(func_name)** - In _DEBUG_ compiling mode, The C++ macro BEGIN_OF - appends the string "Begin of " to the one passed in - argument by the user and displays the result on the - trace buffer pool. In _RELEASE_ compiling mode, this - macro is blank. - - Example:: - - #include "utilities.h" - int main(int argc , char **argv) - { - BEGIN_OF(argv[0]); - return 0; - } - - displays:: - - - Trace main.cxx [3] : Begin of a.out - - -**END_OF(func_name)** - In _DEBUG_ compiling mode, The C++ macro END_OF appends - the string "Normal end of " to the one passed in - argument by the user and displays the result on the - trace buffer pool. In _RELEASE_ compiling mode, this - macro is blank. - - Example:: - - #include "utilities.h" - int main(int argc , char **argv) - { - END_OF(argv[0]); - return 0; - } - - displays:: - - - Trace main.cxx [4] : Normal end of a.out - -**SCRUTE(var)** - In _DEBUG_ compiling mode, The C++ macro SCRUTE - displays its argument which is an application variable - followed by the value of the variable. In _RELEASE_ - compiling mode, this macro is blank. - - Example:: - - #include "utilities.h" - int main(int argc , char **argv) - { - const int i=999; - if( i > 0 ) SCRUTE(i) ; i=i+1; - return 0; - } - - displays:: - - - Trace main.cxx [5] : i=999 - -**ASSERT(condition)** - In _DEBUG_ compiling mode only, The C++ macro ASSERT - checks the expression passed in argument to be not - NULL. If it is NULL the condition is written with the - macro INTERRUPTION (see above). The process exits after - trace of this last message. In _RELEASE_ compiling - mode, this macro is blank. N.B. : if ASSERT is already - defined, this macro is ignored. - - Example:: - - #include "utilities.h" - ... - const char *ptrS = fonc(); - ASSERT(ptrS!=NULL); - cout << strlen(ptrS); - float table[10]; - int k; - ... - ASSERT(k<10); - cout << table[k]; - -Exceptions -========== - -C++ exceptions: class SALOME_Exception --------------------------------------- - -definition -~~~~~~~~~~ - -The class SALOME_Exception provides a generic method to -send a message, with optional source file name and line -number. This class is intended to serve as a base class -for all kinds of exceptions SALOME code. All the -exceptions derived from SALOME_Exception could be -handled in a single catch, in which the message -associated to the exception is displayed, or sent to a -log file. - -The class SALOME_Exception inherits its behavior from -the STL class exception. - -usage -~~~~~ - -The header SALOME/src/utils/utils_SALOME_Exception.hxx -must be included in the C++ source, when raised or trapped:: - - #include "utils_SALOME_Exception.hxx" - -The SALOME_Exception constructor is:: - - SALOME_Exception( const char *text, - const char *fileName=0, - const unsigned int lineNumber=0 ); - -The exception is raised like this:: - - throw SALOME_Exception("my pertinent message"); - -or like this:: - - throw SALOME_Exception(LOCALIZED("my pertinent message")); - -where LOCALIZED is a macro provided with -``utils_SALOME_Exception.hxx`` which gives file name and -line number. - -The exception is handled like this:: - - try - { - ... - } - catch (const SALOME_Exception &ex) - { - cerr << ex.what() <::Instance() ; - assert(ptrPoint!=NULL) ; - -No need to delete ptrPoint. Deletion is achieved -automatically at exit. If the user tries to create more -than one singleton by using the class method -SINGLETON_::Instance(), the pointer is returned -with the same value even if this is done in different -functions (threads ?):: - - POINT *p1=SINGLETON_::Instance() ; - ... - POINT *p2=SINGLETON_::Instance() ; - - assert(p1==p2) - -Design description -~~~~~~~~~~~~~~~~~~ - -Here are the principles features of the singleton -design: - -* the user creates an object of class TYPE by using the - class method ``SINGLETON_::Instance()`` which - returns a pointer to the single object ; - -* to create an object, ``SINGLETON_::Instance()`` - uses the default constructor of class TYPE ; - -* at the same time, this class method creates a - destructor object which is added to the generic list - of destructor objects to be executed at the end of - the application (atexit) ; - -* at the end of the application process all the - deletions are performed by the ``Nettoyage()`` C function - which executes the destruction objects end then - deletes the destructions objects themselves ; - -* the ``Nettoyage()`` C function using ``atexit()`` C function - is embedded in a static single object ``ATEXIT_()``. - - -------------------------------------------------------------------------------- - -+----------------------------------+------------------------------------------+ -| `General KERNEL documentation`_ | `End User KERNEL Doxygen documentation`_ | -+----------------------------------+------------------------------------------+ - -.. _`General KERNEL documentation`: ./index.html -.. _`End User KERNEL Doxygen documentation`: ./tui/KERNEL/index.html diff --git a/doc/docutils/archives/rst.css b/doc/docutils/archives/rst.css deleted file mode 100644 index 38bd7dcab..000000000 --- a/doc/docutils/archives/rst.css +++ /dev/null @@ -1,288 +0,0 @@ -/* -:Authors: David Goodger, David Abrahams -:Contact: goodger@users.sourceforge.net, dave@boost-consulting.com -:date: $Date$ -:version: $Revision$ -:copyright: This stylesheet has been placed in the public domain. - -This stylesheet is for the use of ReStructuredText in a Boost context. -It is basically an agglomeration of boost.css and the default.css that -comes from docutils. - - */ - -.first { - margin-top: 0 } - -.last { - margin-bottom: 0 } - -a.toc-backref { - text-decoration: none ; - color: #00008B } - -dd { - margin-bottom: 0.5em } - -div.abstract { - margin: 2em 5em } - -div.abstract p.topic-title { - font-weight: bold ; - text-align: center } - -div.attention, div.caution, div.danger, div.error, div.hint, -div.important, div.note, div.tip, div.warning, div.admonition { - margin: 2em ; - border: medium outset ; - padding: 1em } - -div.attention p.admonition-title, div.caution p.admonition-title, -div.danger p.admonition-title, div.error p.admonition-title, -div.warning p.admonition-title { - color: red ; - font-weight: bold ; - font-family: sans-serif } - -div.hint p.admonition-title, div.important p.admonition-title, -div.note p.admonition-title, div.tip p.admonition-title, -div.admonition p.admonition-title { - font-weight: bold ; - font-family: sans-serif } - -div.dedication { - margin: 2em 5em ; - text-align: center ; - font-style: italic } - -div.dedication p.topic-title { - font-weight: bold ; - font-style: normal } - -div.figure { - margin-left: 2em } - -div.footer, div.header { - font-size: smaller } - -div.sidebar { - margin-left: 1em ; - border: medium outset ; - padding: 0em 1em ; - background-color: #ffffee ; - width: 40% ; - float: right ; - clear: right } - -div.sidebar p.rubric { - font-family: sans-serif ; - font-size: medium } - -div.system-messages { - margin: 5em } - -div.system-messages h1 { - color: red } - -div.system-message { - border: medium outset ; - padding: 1em } - -div.system-message p.system-message-title { - color: red ; - font-weight: bold } - -div.topic { - margin: 2em } - -H1.title -{ - FONT-SIZE: 150%; - COLOR: #00008B; - text-align: center -} -H1 -{ - FONT-SIZE: 125%; -} -H2 -{ - FONT-SIZE: 108%; -} -h2.subtitle { - text-align: center } -H3 -{ - FONT-SIZE: 100%; -} -BODY -{ - FONT-SIZE: 100%; - BACKGROUND-COLOR: #ffffff; -} -PRE -{ - MARGIN-LEFT: 2em; - FONT-FAMILY: Courier; -} -CODE -{ - FONT-FAMILY: Courier; - white-space: pre; -} -.pre -{ - FONT-FAMILY: Courier; - white-space: pre; -} -.index -{ - TEXT-ALIGN: left; -} -.page-index -{ - TEXT-ALIGN: left; -} -.definition -{ - TEXT-ALIGN: left; -} -.footnote -{ - FONT-SIZE: 66%; - VERTICAL-ALIGN: super; - TEXT-DECORATION: none; -} -.function-semantics -{ - CLEAR: left; -} - -hr { - width: 75% } - -ol.simple, ul.simple { - margin-bottom: 1em } - -ol.arabic { - list-style: decimal } - -ol.loweralpha { - list-style: lower-alpha } - -ol.upperalpha { - list-style: upper-alpha } - -ol.lowerroman { - list-style: lower-roman } - -ol.upperroman { - list-style: upper-roman } - -p.attribution { - text-align: right ; - margin-left: 50% } - -p.caption { - font-style: italic } - -p.credits { - font-style: italic ; - font-size: smaller } - -p.label { - white-space: nowrap } - -p.rubric { - font-weight: bold ; - font-size: larger ; - color: maroon ; - text-align: center } - -p.sidebar-title { - font-family: sans-serif ; - font-weight: bold ; - font-size: larger } - -p.sidebar-subtitle { - font-family: sans-serif ; - font-weight: bold } - -p.topic-title { - font-weight: bold } - -pre.address { - margin-bottom: 0 ; - margin-top: 0 ; - font-family: serif ; - font-size: 100% } - -pre.line-block { - font-family: serif ; - font-size: 100% } - -pre.literal-block, pre.doctest-block { - margin-left: 2em ; - margin-right: 2em ; - font-size: 80%; - border: solid thin gray ; - background-color: #eeeeee } - -span.classifier { - font-family: sans-serif ; - font-style: oblique } - -span.classifier-delimiter { - font-family: sans-serif ; - font-weight: bold } - -span.interpreted { - font-family: sans-serif } - -span.option { - white-space: nowrap } - -span.option-argument { - font-style: italic } - -span.pre { - white-space: pre } - -span.problematic { - color: red } - -table { - margin-top: 0.5em ; - margin-bottom: 0.5em } - -table.citation { - border-left: solid thin gray ; - padding-left: 0.5ex } - -table.docinfo { - margin: 2em 4em } - -table.footnote { - border-left: solid thin black ; - padding-left: 0.5ex } - -td, th { - padding-left: 0.5em ; - padding-right: 0.5em ; - vertical-align: top } - -th.docinfo-name, th.field-name { - font-weight: bold ; - text-align: left ; - white-space: nowrap } - -/* - dwa 2003/7/29 -- commented out so that it wouldn't override earlier - styles from boost.css - -h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { - font-size: 100% } -*/ - -ul.auto-toc { - list-style-type: none } diff --git a/doc/docutils/archives/txt2html.sh b/doc/docutils/archives/txt2html.sh deleted file mode 100755 index b69186c52..000000000 --- a/doc/docutils/archives/txt2html.sh +++ /dev/null @@ -1,56 +0,0 @@ -#!/bin/sh -# Copyright (C) 2007-2014 CEA/DEN, EDF R&D, OPEN CASCADE -# -# Copyright (C) 2003-2007 OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN, -# CEDRAT, EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS -# -# 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 -# - -# =================================================================== -# This shell script is provided for generating the html files -# from the txt files (restructured text) in the source directory. -# Usage: just execute the script where it stands in the source -# directory. The file list has to be updated manually when adding -# a new restructured text file. -# Note that the building process executes a target rstdoc that -# generates the html documentation without need of this script. -# The autoconficuration (check_htmlgen.m4) set the correct generator -# rst2html by replacing the @RST2HTML@ tag. -# =================================================================== -# (CSSI - gboulant - 25/10/05) -# This must be updated manually in this script (for source usage only) -# -RST2HTML=rst2html - -FILELIST="index - UnitTests - SALOME_Application - INSTALL - kernel_resources - KERNEL_Services - userguide" - -STYLESHEET=rst.css -RSTOPTS="--output-encoding=latin1 --stylesheet=$STYLESHEET" - -for file in $FILELIST; do - bfn=`basename $file .txt` - echo "Generating ${bfn}.html from ${bfn}.txt ..." - $RST2HTML $RSTOPTS ${bfn}.txt ${bfn}.html -done - diff --git a/doc/docutils/archives/userguide.txt b/doc/docutils/archives/userguide.txt deleted file mode 100644 index 119aa1581..000000000 --- a/doc/docutils/archives/userguide.txt +++ /dev/null @@ -1,141 +0,0 @@ -================================================================= -User's guide, for developpers and users -================================================================= - -*html version of this document is produced with docutils*:: - - rst2html < doc.txt > doc.html - -*This document corresponds to SALOME2 3.1.0* -*NOT UP TO DATE with 3.2.0* - -.. contents:: -.. sectnum:: - -+-------------------------------------------+ -| **WORK in PROGRESS, INCOMPLETE DOCUMENT** | -+-------------------------------------------+ - -------------------------------------------------------------------------------- - -This guide provides you with some basic concepts for developing and -using the SALOME platform. You will find some information on the -general technical architecture ... - -Introduction -============ - -General information -------------------- - -This document has been initialized by collecting and updating an existing -documentation. The restructured text format has been selected for -writing. This format can be read with a basic editor except for -pictures and some hypertext links. You can build the html pages using -the docutils scripts provided with python packages on most platform. - -Definitions ------------ - -``WORK IN PROGRESS`` - -Module - definition of a module and/or link to the definition - -Container - definition of a container - - -General concepts -================ -modules et dépendances (s'inspirer de PYHELLO) - - -Filesystem organisation -======================== - -Voir doc de JR "Organisation de la plate-forme" - -A typical source working directory ----------------------------------- -organisation type des sources d'un module standard (spécifications techniques) - -A typical installation directory --------------------------------- -organisation type des produits installés - - -Building process -================ -Procédures de compilation (renvoie au install.sh) - - -Developer's guide - basic concepts -========================================= - -Guide du développeur: éléments de conception - - zoom sur certains éléments techniques bons à connaitre pour faire - évoluer le KERNEL sans tout casser. - - les ressources du kernel: - - trace, debug, exception (cf. kernel_ressources.tex) - - classes batch (présentation puis renvoi à la doc d'Ivan) - - développement de tests unitaires - -Developer's guide - managing the development space -================================================== - -- Guide du développeur: gestion de l'espace de développement - - principe de mise en oeuvre (rôle des étapes: build_configure, ...) - - description des fichiers m4 et du principe de mise en oeuvre - - les Makefile.in, ... (cf. doc guide du développeur). - - évolution des procédures de construction - - personalisation des procédures de construction - -Developer' guide - integration tools -==================================== -- Guide de l'intégrateur (développeur de nouveaux modules) : (on lui montre ici le principe de construction et les ressources à disposition pour faire le travail) - - création d'un modules - - intégration code boîte noire (perfect, solver) - - intégration bibliothèque de fonctions (hxx2salome, voir avec N.Crouzet) - - intégration de modèles de données (xdata) - - -End user's guide -================ -- Guide de l'utilisateur - - concept d'application (renvoie doc Paul) - - commandes avancées (showNS, exemple de contact de la session, d'un engine, utilisation du lifeCycle, du module salome, des modules geompy et smesh) - - utilisation en mode distribué (doc de B. Sechet) - - GUI and TUI documentation - - - - - - - - - - - - - - - -RST Exemples -============ - -See INSTALL_ for general information on required configuration and -prerequisites, compilation procedure, setting environment principles. - -.. _INSTALL: ./INSTALL.html - - -------------------------------------------------------------------------------- - -+----------------------------------+------------------------------------------+ -| `General KERNEL documentation`_ | `End User KERNEL Doxygen documentation`_ | -+----------------------------------+------------------------------------------+ - -.. _`General KERNEL documentation`: ./index.html -.. _`End User KERNEL Doxygen documentation`: ./tui/KERNEL/index.html diff --git a/doc/docutils/conf.py.in b/doc/docutils/conf.py.in deleted file mode 100644 index b2208485e..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 = 'SALOME KERNEL 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 = '@SALOMEKERNEL_VERSION@' -# The full version, including alpha/beta/rc tags. -release = '@SALOMEKERNEL_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 = 'kernelpydoc' - - -# 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', 'kernelpy.tex', 'Documentation of the KERNEL 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 = '../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 fd36cbc19..000000000 --- a/doc/docutils/docapi.rst +++ /dev/null @@ -1,14 +0,0 @@ - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - Documentation of the programming interface (API) -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -This section describes the python modules of the -``salome.kernel`` python package. The main part is generated from the -code documentation included in source python files. - -.. toctree:: - :maxdepth: 3 - - kernel.rst - parametric.rst diff --git a/doc/docutils/index.rst b/doc/docutils/index.rst deleted file mode 100644 index a0b8c3a32..000000000 --- a/doc/docutils/index.rst +++ /dev/null @@ -1,22 +0,0 @@ - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - Documentation of the KERNEL python packages -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -Main documentation -================== - -.. toctree:: - :maxdepth: 3 - - overview.rst - docapi.rst - - -Additional documentation -======================== - -.. toctree:: - :maxdepth: 3 - - salomepypkg.rst diff --git a/doc/docutils/kernel.rst b/doc/docutils/kernel.rst deleted file mode 100644 index 4b7327f92..000000000 --- a/doc/docutils/kernel.rst +++ /dev/null @@ -1,81 +0,0 @@ -:mod:`salome.kernel` -- Package containing the KERNEL python utilities -====================================================================== - -:mod:`deprecation` -- Indication of deprecated modules and functions --------------------------------------------------------------------- - -.. automodule:: salome.kernel.deprecation - :members: - - -:mod:`termcolor` -- Display colored text in terminal ----------------------------------------------------- - -.. automodule:: salome.kernel.termcolor - :members: - :exclude-members: TEST_termcolor - - -:mod:`logger` -- Logging utility --------------------------------- - -.. automodule:: salome.kernel.logger - -.. autoclass:: Logger - :members: - :show-inheritance: - -.. autoclass:: ExtLogger - :members: - :show-inheritance: - -:mod:`enumerate` -- Emulates a C-like enum for python ------------------------------------------------------ - -.. automodule:: salome.kernel.enumerate - :members: - -:mod:`uiexception` -- Exception for user error management ---------------------------------------------------------- - -.. automodule:: salome.kernel.uiexception - :members: - -:mod:`datamodeler` -- Helper for modeling user data ---------------------------------------------------- - -.. automodule:: salome.kernel.datamodeler - :members: - -.. automodule:: salome.kernel.testdata - :members: - -:mod:`diclookup` -- Smart dictionnary with key/value lookup ------------------------------------------------------------ - -.. automodule:: salome.kernel.diclookup - :members: - -:mod:`service` -- Helper for using SALOME kernel services ---------------------------------------------------------- - -.. automodule:: salome.kernel.services - :members: - -:mod:`studyedit` -- Study editor --------------------------------- - -.. automodule:: salome.kernel.studyedit - :members: - -:mod:`unittester` -- Run very basic unit tests ----------------------------------------------- - -.. automodule:: salome.kernel.unittester - :members: - -:mod:`pyunittester` -- Simple wrapper of the pyunit framework -------------------------------------------------------------- - -.. automodule:: salome.kernel.pyunittester - :members: diff --git a/doc/docutils/overview.rst b/doc/docutils/overview.rst deleted file mode 100644 index 950792907..000000000 --- a/doc/docutils/overview.rst +++ /dev/null @@ -1,47 +0,0 @@ - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -General presentation of the KERNEL python package -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -The KERNEL python package essentially contains: - -* Helper functions to manipulate KERNEL objects from python. For - example, the ``studyedit.py`` module facilitates the - manipulation of components and items in SALOME study. -* General purpose functions for logging and other recurrent - stuff in python programming. - -Note that these functions either encapsulate the python programming -interface of KERNEL core (the CORBA or SWIG interfaces for example) or -extend existing utilities as the ``salome*.py`` modules. - -The functions are distributed in the python package -``salome.kernel``. For example, the usage of the study editor to -manipulate some objects can be done with a set of instructions as: - -.. code-block:: python - - from salome.kernel.studyedit import getStudyEditor - - studyEditor = getStudyEditor() # Get an editor for the current study - - myStudyComponent = studyEditor.findOrCreateComponent( - moduleName, - componentName, - componentIcon) - - myStudyItem = studyEditor.createItem( - myStudyComponent, - itemName, - comment = itemComment, - icon = itemIcon) - -The specification of the programming interface of this package is -detailed 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 GEOM - module provides the python package ``salome.geom`` and SMESH the - package ``salome.smesh``. diff --git a/doc/docutils/parametric.rst b/doc/docutils/parametric.rst deleted file mode 100644 index f868080f0..000000000 --- a/doc/docutils/parametric.rst +++ /dev/null @@ -1,22 +0,0 @@ -:mod:`salome.kernel.parametric` -- Package for parametric studies -================================================================= - -:mod:`study_exchange_vars` -- Handle Exchange Variables -------------------------------------------------------- - -.. automodule:: salome.kernel.parametric.study_exchange_vars - :members: - - -:mod:`compo_utils` -- Useful functions for SALOME components used in parametric studies ---------------------------------------------------------------------------------------- - -.. automodule:: salome.kernel.parametric.compo_utils - :members: - - -:mod:`pyscript_utils` -- Useful functions for Python scripts used in parametric studies ---------------------------------------------------------------------------------------- - -.. automodule:: salome.kernel.parametric.pyscript_utils - :members: diff --git a/doc/docutils/salomepypkg.rst b/doc/docutils/salomepypkg.rst deleted file mode 100644 index f17285ec7..000000000 --- a/doc/docutils/salomepypkg.rst +++ /dev/null @@ -1,271 +0,0 @@ - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -Complement A: Organizing the SALOME python functions in a packaged structure -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -This chapter contains the instruction notes to organise the python -files of SALOME in a packaged python structure. This is the first step -of the development process, whose goal is to validate the principles -and show a possible way. - -:Contacts: Guillaume Boulant, Christian Caremoli, Renaud Barate - -Objectives -========== - -The main idea is to import SALOME python functions by doing: - -.. code-block:: python - - from salome.kernel. import - -instead of: - -.. code-block:: python - - from import - -as it must be done up to now because of the flat organisation of -python files in the installation folders of SALOME modules. - -To reach this target, the files ``.py`` have to be -organised in a packaged python structure where the main package is -named ``salome``, and then sub-packages could be created for each -SALOME module: - -* ``salome.kernel``: for kernel python functions, embedded in the - KERNEL module -* ``salome.gui``: for gui python functions, embedded in the GUI module -* ``salome.geom``: for geom python functions, embedded in the GEOM - module -* and so on ... - -The motivations of this objective are twice: - -* Definitively prevent the risk of naming conflict between python - modules coming from different SALOME modules. Today, the developper - of a module has to take care of the names used in other modules to - choose a name. -* Integrate in SALOME some python modules initialy developed in the - context of domain specific SALOME applications (SALOME-MECA, - SALOME-CFD, OPENTURN, PANTHERE) and whose source files are organized - in a packaged python structure. - -The starting point then is a python library named ``nepal`` that -provides SALOME helper functions classified by modules -(KERNEL,GEOM,...) and organized in a packaged python structure: - -* ``salome.kernel``: helper functions for manipulating the SALOME - study and its components (SComponents and SObject). This provides - also general purpose utilities for logging and threading. -* ``salome.gui``: helper functions to manipulate the graphical - representation of studies and the general behavior of the graphical - interface. This provides also generic templates for implementing - dialog box with the MVC pattern. -* ``salome.geom``: essentially contains a function called - "visualization of structural elements". This is used by mechanical - ingeneers to create the 3D geometrical object corresponding to the - numerical model of a given structural element. -* ``salome.smesh``: to manipulated smesh data handled from the SObject - in the SALOME study. - -The target point is to have the ``salome.kernel`` part in the KERNEL -module, the ``salome.geom`` part in the GEOM module, and so on. And -with **no impact on SALOME scripts** that already exists (import salome, -and all other stuff should be imported and work as before). - - -Problems -======== - -To reach this target, we have to face two problems: - -* A naming conflict with the instruction ``import salome``. The result - is unpredictible because of the existance in the ``sys.path`` of - both a file ``salome.py`` and a package ``salome``. -* The dispatching of ``salome.*`` sub-packages in the different SALOME - modules. - -Naming conflict between ``salome.py`` module and ``salome`` package -------------------------------------------------------------------- - -The problem is solved by installing the ``salome.py`` file under the -name ``__init__.py`` in a folder named ``${salomepythondir}/salome``. - -By this operation, the ``${salomepythondir}/salome`` directory is -transformed in a python package and the instruction ``import salome`` -do the same things as before this modification, without any -modification of the ``sys.path``. - -Dispatching of ``salome.*`` sub-packages in different SALOME modules --------------------------------------------------------------------- - -When we use a SALOME virtual application, the problem is naturally -solved by the fact that every sub-packages are virtually installed in -the same directory, the directory ``${salomepythondir}/salome`` -containing the file ``__init__.py``. - -Nevertheless, some people doesn't use the virtual application. To get -a robust configuration in any case, one can use the python namespace -pattern. This consists in creating a virtual python package that -aggregates all the sub-packages. - -Technically speaking, this consists in implementing in the file -``${salomepythondir}/salome/__init__.py`` (new version of -``salome.py``) a function that automatically extend the ``__path__`` -variable with sub-packages that can be found in SALOME modules -installation paths. The code looks something like that: - -.. code-block:: python - - import os, sys - - MATCH_ENDING_PATTERN="site-packages/salome" - - def extend_path(pname): - for dir in sys.path: - if not isinstance(dir, basestring) or not os.path.isdir(dir) or not dir.endswith(MATCH_ENDING_PATTERN): - continue - subdir = os.path.join(dir, pname) - # WARN: This may still add duplicate entries to path on - # case-insensitive filesystems - if os.path.isdir(subdir) and subdir not in __path__: - print "INFO - The directory %s is appended to sys.path" % subdir - __path__.append(subdir) - - extend_path(ROOT_PYTHONPACKAGE_NAME) - - -Adaptation of the ``apply_gen`` utility ----------------------------------------- - -Due to the specific above choices, the ``apply_gen`` utility must be -modified so that the sub-folder ``salome`` in ``${salomepythondir}`` -is not generated as a symbolic link any longer but as a real folder -containing symbolic links towards the module specific python -sub-packages (``kernel``, ``geom``, ``smesh``, ...) and to the single -file ``__init__.py`` provided by the KERNEL module. - -This adaptation can be done in the ``virtual_salome.py`` script. - - -What to do with already existing python files? ----------------------------------------------- - -Do nothing at this step, it works fine because the files are installed -in a path included in the ``sys.path``. - -In a future version, it should be nice to reverse all the python files -of the KERNEL library in this packaged structure. But this can't be -done without impact on existing python user scripts. - -Instructions -============ - -Instructions for creating the python packages ---------------------------------------------- - -Considering the elements described above, a procedure that works to -get the packaged python structure is: - -* Rename the file ``salome.py`` in ``__init__.py`` (and adapt the - CMakeLists.txt). This is located in the source directory - ``src/KERNEL_PY``. -* Copy the sources files of the kernel part in the source directory - ``src/KERNEL_PY`` starting with a stage named ``kernel`` including - its own packaged structure (only python files and a file - ``__init__.py`` for now) -* Copy the sources files of the geom part in the source directory - ``src/GEOM_PY`` (to be created) of the GEOM module. In this case, we - copy the python files directly in the directory (no stage named - ``geom``, it's not required for source organisation, and will be - created only for installation by makefile). -* Apply the same procedure for every other SALOME modules (it concerns - only SMESH up to now). -* Apply the "namespace pattern" by implementing and invoking the - ``extend_path`` function in the newly created file ``__init__.py`` -* Adapt the ``apply_gen`` utility to take into account the finer - folder hierarchy in ``site-packages``. - -The naming convention for source folder is here the convention in -place in the KERNEL module: the source code of the python packages of -a SALOME module is located in the source directory -``/src/_PY``. - -Note also that all python files that were existing in the KERNEL -module are leaft untouched but the file ``salome.py``. - -Instructions for the associated documentation ---------------------------------------------- - -One special point for the documentation: - -* The documentation of the python package API is writen in rst - (restructured text) and generated form the source code with sphinx. -* The rst source files are located in the directory - ``/doc/docutils``. -* The html generated files are installed in the directory - ``/share/doc/salome/docutils`` but are not connected to - the in-line documentation of the SALOME associated module (menu help - of the SALOME application). - -Any suggestion on this point would be appreciated. - -TODO (by someone): - -* Move all files ``*.txt`` from the ``/doc`` folder to the - ``/doc/docutils`` folder and analyse what is still to date - and usefull. -* Integrate in this part the reference documentation of the ``salome`` - utility and all documentation associated to the launching process - (in particular virtual application) -* Connect this part of the documentation to the main part (doxygen - part). - - -Synthesis ---------- - -Finaly, here is a synthesis of modifications in source files. - -Files modified: - -* See the CVS patch files KERNEL.patch, GEOM.patch and SMESH.patch - (the only SALOME modules modified today). - -Files to be added: - -* KERNEL: file ``src/KERNEL_PY/__init__.py`` (``salome.py`` renamed) -* KERNEL: directory ``src/KERNEL_PY/kernel`` -* KERNEL: directory ``doc/docutils`` -* KERNEL: file ``salome_adm/cmake_files/FindSalomeSphinx.cmake`` -* KERNEL: file ``salome_adm/cmake_files/FindSphinx.cmake`` -* GEOM : directory ``src/GEOM_PY`` -* GEOM : directory ``doc/docutils`` -* SMESH : directory ``src/SMESH_PY`` -* SMESH : directory ``doc/docutils`` - -Files to be delete: - -* file ``src/KERNEL_PY/salome.py`` - - -Tests and usage -=============== - -The instructions above provides you with a SALOME application whose -modules embed there dedicated python packages. This installation can -can be tested using some test use cases. For example, the -visualisation of structural elements (provided by the package -``salome.geom`` can be tested by: - -.. code-block:: python - - from salome.geom.structelem import TEST_StructuralElement - TEST_StructuralElement() - -This can be enter in the GUI python console or in a python interpreter -executed in a SALOME session. - -For more details, read the API documentation in -``/share/doc/salome/docutils``. diff --git a/doc/salome/gui/CMakeLists.txt b/doc/salome/gui/CMakeLists.txt index 7ce965b17..00401e563 100755 --- a/doc/salome/gui/CMakeLists.txt +++ b/doc/salome/gui/CMakeLists.txt @@ -17,10 +17,42 @@ # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com # +INCLUDE(${CMAKE_SOURCE_DIR}/salome_adm/cmake_files/SalomeMacros.cmake) + SALOME_CONFIGURE_FILE(doxyfile.in doxyfile) SALOME_CONFIGURE_FILE(static/header.html.in static/header.html) -ADD_CUSTOM_TARGET(usr_docs ${DOXYGEN_EXECUTABLE}) +SET(gen_doc "${CMAKE_SOURCE_DIR}/salome_adm/cmake_files/prepare_generating_doc.py") +IF(WIN32) + STRING(REPLACE "/" "\\" gen_doc ${gen_doc}) +ENDIF(WIN32) +SET(kernel_py ${CMAKE_SOURCE_DIR}/src/KERNEL_PY) + +ADD_CUSTOM_TARGET(usr_docs ${CMAKE_COMMAND} -E make_directory tmp + COMMAND ${PYTHON_EXECUTABLE} ${gen_doc} -o tmp/kernel.py ${kernel_py}/kernel/__init__.py + COMMAND ${PYTHON_EXECUTABLE} ${gen_doc} -o tmp/deprecation.py ${kernel_py}/kernel/deprecation.py + COMMAND ${PYTHON_EXECUTABLE} ${gen_doc} -o tmp/termcolor.py ${kernel_py}/kernel/termcolor.py + COMMAND ${PYTHON_EXECUTABLE} ${gen_doc} -o tmp/logger.py ${kernel_py}/kernel/logger.py + COMMAND ${PYTHON_EXECUTABLE} ${gen_doc} -o tmp/enumerate.py ${kernel_py}/kernel/enumerate.py + COMMAND ${PYTHON_EXECUTABLE} ${gen_doc} -o tmp/uiexception.py ${kernel_py}/kernel/uiexception.py + COMMAND ${PYTHON_EXECUTABLE} ${gen_doc} -o tmp/datamodeler.py ${kernel_py}/kernel/datamodeler.py + COMMAND ${PYTHON_EXECUTABLE} ${gen_doc} -o tmp/diclookup.py ${kernel_py}/kernel/diclookup.py + COMMAND ${PYTHON_EXECUTABLE} ${gen_doc} -o tmp/services.py ${kernel_py}/kernel/services.py + COMMAND ${PYTHON_EXECUTABLE} ${gen_doc} -o tmp/studyedit.py ${kernel_py}/kernel/studyedit.py + COMMAND ${PYTHON_EXECUTABLE} ${gen_doc} -o tmp/unittester.py ${kernel_py}/kernel/unittester.py + COMMAND ${PYTHON_EXECUTABLE} ${gen_doc} -o tmp/pyunittester.py ${kernel_py}/kernel/pyunittester.py + COMMAND ${PYTHON_EXECUTABLE} ${gen_doc} -o tmp/parametric.py ${kernel_py}/kernel/parametric/__init__.py + COMMAND ${PYTHON_EXECUTABLE} ${gen_doc} -o tmp/study_exchange_vars.py ${kernel_py}/kernel/parametric/study_exchange_vars.py + COMMAND ${PYTHON_EXECUTABLE} ${gen_doc} -o tmp/compo_utils.py ${kernel_py}/kernel/parametric/compo_utils.py + COMMAND ${PYTHON_EXECUTABLE} ${gen_doc} -o tmp/pyscript_utils.py ${kernel_py}/kernel/parametric/pyscript_utils.py + COMMAND ${PYTHON_EXECUTABLE} ${gen_doc} -o tmp/salome.py ${kernel_py}/__init__.py + COMMAND ${PYTHON_EXECUTABLE} ${gen_doc} -o tmp/salome_iapp.py ${kernel_py}/salome_iapp.py + COMMAND ${PYTHON_EXECUTABLE} ${gen_doc} -o tmp/SALOME_DriverPy.py ${CMAKE_SOURCE_DIR}/src/SALOMEDS/SALOME_DriverPy.py + COMMAND ${DOXYGEN_EXECUTABLE} doxyfile + COMMAND ${CMAKE_COMMAND} -E remove_directory tmp + VERBATIM + WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} +) ADD_DEPENDENCIES(usr_docs html_docs) diff --git a/doc/salome/gui/doxyfile.in b/doc/salome/gui/doxyfile.in index af2f44c69..fc5033f5a 100644 --- a/doc/salome/gui/doxyfile.in +++ b/doc/salome/gui/doxyfile.in @@ -76,6 +76,7 @@ WARN_LOGFILE = log.txt # configuration options related to the input files #--------------------------------------------------------------------------- INPUT = \ + @CMAKE_CURRENT_BINARY_DIR@/tmp \ @PROJECT_SOURCE_DIR@/doc/salome \ @PROJECT_SOURCE_DIR@/bin \ @PROJECT_SOURCE_DIR@/idl \ @@ -83,9 +84,6 @@ INPUT = \ @PROJECT_SOURCE_DIR@/src/LifeCycleCORBA \ @PROJECT_SOURCE_DIR@/src/NamingService \ @PROJECT_SOURCE_DIR@/src/Notification \ - @PROJECT_SOURCE_DIR@/src/SALOMEDS/SALOME_DriverPy.py \ - @PROJECT_SOURCE_DIR@/src/KERNEL_PY/salome.py \ - @PROJECT_SOURCE_DIR@/src/KERNEL_PY/salome_iapp.py \ @PROJECT_SOURCE_DIR@/src/Utils \ @PROJECT_SOURCE_DIR@/src/DSC diff --git a/doc/salome/main.dox b/doc/salome/main.dox index 850784f5a..3aa35fe5c 100644 --- a/doc/salome/main.dox +++ b/doc/salome/main.dox @@ -61,8 +61,7 @@ specific points of %SALOME Kernel : - \subpage kernel_salome - \subpage dsc_page : DSC documentation page. - \subpage salome_file_page : Salome_file documentation page. -- - Documentation of the KERNEL python package : The package salome.kernel provides +- \subpage python_documentation : The package salome.kernel provides logging tools, high-level functions to handle items in Salome study, and other utilities. */ diff --git a/doc/salome/python_doc_api.dox b/doc/salome/python_doc_api.dox new file mode 100644 index 000000000..d013f7af1 --- /dev/null +++ b/doc/salome/python_doc_api.dox @@ -0,0 +1,27 @@ +/*! + +\page python_doc_api Documentation of the programming interface (API) + +This section describes the python modules of the salome.kernel +python package. The main part is generated from the code documentation +included in source python files. +- salome.kernel - Package containing + the KERNEL python utilities + - deprecation - Indication of deprecated modules and functions + - termcolor - Display colored text in terminal + - logger - Logging utility + - enumerate - Emulates a C-like enum for python + - uiexception - %Exception for user error management + - datamodeler - Helper for modeling user data + - diclookup - Smart dictionnary with key/value lookup + - service - Helper for using %SALOME kernel services + - studyedit - Study editor + - unittester - Run very basic unit tests + - pyunittester - Simple wrapper of the pyunit framework +- salome.kernel.parametric - + Package for parametric studies + - study_exchange_vars - Handle Exchange Variables + - compo_utils - Useful functions for %SALOME components used in parametric studies + - pyscript_utils - Useful functions for Python scripts used in parametric studies + +*/ diff --git a/doc/salome/python_doc_compl.dox b/doc/salome/python_doc_compl.dox new file mode 100644 index 000000000..475f8ecff --- /dev/null +++ b/doc/salome/python_doc_compl.dox @@ -0,0 +1,214 @@ +/*! + +\page python_doc_compl Organizing the SALOME python functions in a packaged structure + +This chapter contains the instruction notes to organise the python files of %SALOME +in a packaged python structure. This is the first step of the development process, +whose goal is to validate the principles and show a possible way. + +\b Contacts: Guillaume Boulant, Christian Caremoli, Renaud Barate + +\section Compl_objectives Objectives + +The main idea is to import %SALOME python functions by doing: + +\code +from salome.kernel. import +\endcode + +instead of: + +\code +from import +\endcode + +as it must be done up to now because of the flat organisation of +python files in the installation folders of %SALOME modules. + +To reach this target, the files .py have to be +organised in a packaged python structure where the main package is +named salome, and then sub-packages could be created for each +%SALOME module: + +- salome.kernel: for kernel python functions, embedded in the + KERNEL module +- salome.gui: for gui python functions, embedded in the GUI module +- salome.geom: for geom python functions, embedded in the GEOM + module +- and so on ... + +The motivations of this objective are twice: + +- Definitively prevent the risk of naming conflict between python + modules coming from different %SALOME modules. Today, the developper + of a module has to take care of the names used in other modules to + choose a name. +- Integrate in %SALOME some python modules initialy developed in the + context of domain specific %SALOME applications (%SALOME-MECA, + %SALOME-CFD, OPENTURN, PANTHERE) and whose source files are organized + in a packaged python structure. + +The starting point then is a python library named \em nepal that +provides %SALOME helper functions classified by modules +(KERNEL,GEOM,...) and organized in a packaged python structure: + +- salome.kernel: helper functions for manipulating the %SALOME + study and its components (SComponents and SObject). This provides + also general purpose utilities for logging and threading. +- salome.gui: helper functions to manipulate the graphical + representation of studies and the general behavior of the graphical + interface. This provides also generic templates for implementing + dialog box with the MVC pattern. +- salome.geom: essentially contains a function called + "visualization of structural elements". This is used by mechanical + ingeneers to create the 3D geometrical object corresponding to the + numerical model of a given structural element. +- salome.smesh: to manipulated smesh data handled from the SObject + in the %SALOME study. + +The target point is to have the salome.kernel part in the KERNEL +module, the salome.geom part in the GEOM module, and so on. And +with no impact on %SALOME scripts that already exists (import salome, +and all other stuff should be imported and work as before). + +\section Compl_problems Problems + +To reach this target, we have to face two problems: + +- %A naming conflict with the instruction import salome. The result + is unpredictible because of the existance in the sys.path of + both a file salome.py and a package \b salome. +- The dispatching of salome.* sub-packages in the different %SALOME + modules. + +\subsection subsection_prob1 Naming conflict between salome.py module and salome package + +The problem is solved by installing the salome.py file under the +name __init__.py in a folder named ${salomepythondir}/salome. + +By this operation, the ${salomepythondir}/salome directory is +transformed in a python package and the instruction import salome +do the same things as before this modification, without any +modification of the sys.path. + +\subsection subsection_prob2 Dispatching of salome.* sub-packages in different %SALOME modules + +When we use a %SALOME virtual application, the problem is naturally +solved by the fact that every sub-packages are virtually installed in +the same directory, the directory ${salomepythondir}/salome +containing the file __init__.py. + +Nevertheless, some people doesn't use the virtual application. To get +a robust configuration in any case, one can use the python namespace +pattern. This consists in creating a virtual python package that +aggregates all the sub-packages. + +Technically speaking, this consists in implementing in the file +${salomepythondir}/salome/__init__.py (new version of +salome.py) a function that automatically extend the __path__ +variable with sub-packages that can be found in %SALOME modules +installation paths. The code looks something like that: + +\code +import os, sys +MATCH_ENDING_PATTERN="site-packages/salome" +def extend_path(pname): + for dir in sys.path: + if not isinstance(dir, basestring) or not os.path.isdir(dir) or not dir.endswith(MATCH_ENDING_PATTERN): + continue + subdir = os.path.join(dir, pname) + # WARN: This may still add duplicate entries to path on + # case-insensitive filesystems + if os.path.isdir(subdir) and subdir not in __path__: + print "INFO - The directory %s is appended to sys.path" % subdir + __path__.append(subdir) + +extend_path(ROOT_PYTHONPACKAGE_NAME) +\endcode + +\subsection subsection_prob3 Adaptation of the apply_gen utility + +Due to the specific above choices, the apply_gen utility must be +modified so that the sub-folder \b salome in ${salomepythondir} +is not generated as a symbolic link any longer but as a real folder +containing symbolic links towards the module specific python +sub-packages (\b kernel, \b geom, \b smesh, ...) and to the single +file __init__.py provided by the KERNEL module. + +This adaptation can be done in the virtual_salome.py script. + +\subsection subsection_prob4 What to do with already existing python files? + +Do nothing at this step, it works fine because the files are installed +in a path included in the sys.path. + +In a future version, it should be nice to reverse all the python files +of the KERNEL library in this packaged structure. But this can't be +done without impact on existing python user scripts. + +\section Compl_instructions Instructions + +\subsection subsection_instr1 Instructions for creating the python packages + +Considering the elements described above, a procedure that works to +get the packaged python structure is: + +- Rename the file salome.py in __init__.py (and adapt the + CMakeLists.txt). This is located in the source directory + src/KERNEL_PY. +- Copy the sources files of the kernel part in the source directory + src/KERNEL_PY starting with a stage named \b kernel including + its own packaged structure (only python files and a file + __init__.py for now) +- Copy the sources files of the geom part in the source directory + src/GEOM_PY (to be created) of the GEOM module. In this case, we + copy the python files directly in the directory (no stage named + \b geom, it's not required for source organisation, and will be + created only for installation by makefile). +- Apply the same procedure for every other %SALOME modules (it concerns + only SMESH up to now). +- Apply the "namespace pattern" by implementing and invoking the + extend_path function in the newly created file __init__.py +- Adapt the apply_gen utility to take into account the finer + folder hierarchy in site-packages. + +The naming convention for source folder is here the convention in +place in the KERNEL module: the source code of the python packages of +a %SALOME module is located in the source directory +/src/_PY. + +Note also that all python files that were existing in the KERNEL +module are leaft untouched but the file salome.py. + +\subsection subsection_instr2 Instructions for the associated documentation + +One special point for the documentation: + +- The documentation of the python package API is writen in HTML + and generated form the source code with doxygen. +- The *.dox (doxygen file) source files are located in the directory + /doc/salome. +- The html generated files are installed in the directory + /share/doc/salome/gui/KERNEL and are connected to + the in-line documentation of the %SALOME associated module (menu help + of the %SALOME application). + +\section Compl_tests Tests and usage + +The instructions above provides you with a %SALOME application whose +modules embed there dedicated python packages. This installation can +can be tested using some test use cases. For example, the +visualisation of structural elements (provided by the package +salome.geom can be tested by: + +\code +from salome.geom.structelem import TEST_StructuralElement +TEST_StructuralElement() +\endcode + +This can be enter in the GUI python console or in a python interpreter +executed in a %SALOME session. + +For more details, read the \ref python_doc_api "API documentation" in +/share/doc/salome/gui/KERNEL. +*/ diff --git a/doc/salome/python_doc_generale.dox b/doc/salome/python_doc_generale.dox new file mode 100644 index 000000000..598976d8c --- /dev/null +++ b/doc/salome/python_doc_generale.dox @@ -0,0 +1,45 @@ +/*! + +\page python_doc_generale General presentation of the KERNEL python package + +The KERNEL python package essentially contains: + +- Helper functions to manipulate KERNEL objects from python. For + example, the studyedit.py module facilitates the + manipulation of components and items in %SALOME study. +- General purpose functions for logging and other recurrent + stuff in python programming. + +Note that these functions either encapsulate the python programming +interface of KERNEL core (the CORBA or SWIG interfaces for example) or +extend existing utilities as the salome*.py modules. + +The functions are distributed in the python package +salome.kernel. For example, the usage +of the study editor to manipulate some objects can be done with a set +of instructions as: + +\code +from salome.kernel.studyedit import getStudyEditor + +studyEditor = getStudyEditor() # Get an editor for the current study + +myStudyComponent = studyEditor.findOrCreateComponent( moduleName, + componentName, + componentIcon ) +myStudyItem = studyEditor.createItem( myStudyComponent, + itemName, + comment = itemComment, + icon = itemIcon ) +\endcode + +The specification of the programming interface of this package is +detailed in the part \ref python_doc_api of this documentation. + +\note +The main package \b salome contains other sub-packages that are +distributed with the other %SALOME modules. For example, the GEOM +module provides the python package \b salome.geom and SMESH the +package \b salome.smesh. + +*/ diff --git a/doc/salome/python_documentation.dox b/doc/salome/python_documentation.dox new file mode 100644 index 000000000..f87a434bb --- /dev/null +++ b/doc/salome/python_documentation.dox @@ -0,0 +1,7 @@ +/*! + \page python_documentation Documentation of the KERNEL python package + + - \subpage python_doc_generale + - \subpage python_doc_api + - \subpage python_doc_compl +*/ diff --git a/src/KERNEL_PY/kernel/__init__.py b/src/KERNEL_PY/kernel/__init__.py index f6c89e02e..1449e0522 100644 --- a/src/KERNEL_PY/kernel/__init__.py +++ b/src/KERNEL_PY/kernel/__init__.py @@ -18,6 +18,22 @@ # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com # +## \defgroup salome_kernel salome.kernel +# \{ +# \details Package containing the KERNEL python utilities +# \defgroup deprecation +# \defgroup termcolor +# \defgroup logger +# \defgroup enumerate +# \defgroup uiexception +# \defgroup datamodeler +# \defgroup diclookup +# \defgroup service +# \defgroup studyedit +# \defgroup unittester +# \defgroup pyunittester +# \} + __all__ = [ "deprecation", "logger", "termcolor", "logconfig" ] # WARN: This file SHOULD NOT import salome stuff so that modules of the diff --git a/src/KERNEL_PY/kernel/datamodeler.py b/src/KERNEL_PY/kernel/datamodeler.py index bf6cd57e9..5100246ca 100644 --- a/src/KERNEL_PY/kernel/datamodeler.py +++ b/src/KERNEL_PY/kernel/datamodeler.py @@ -18,6 +18,11 @@ # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com # +## \defgroup datamodeler datamodeler +# \{ +# \details Helper for modeling user data +# \} + __author__="gboulant" __date__ ="$15 avr. 2010 19:44:17$" @@ -43,6 +48,24 @@ UNCHECKED_ATTRIBUTES = [ "_voidmap" ] +## This class is a placeholder for modeling data. An object based on this class +# (particular instance or specialized derived class) can defined attributes with +# the following properties: +# - a type : the class or the type of the attribute. Setting an attribute to +# a value whose type is not the specified type raises an exception. +# - a range : a list of the possible values for the attribute. Setting an +# attribute to a value not in the range raises an exception +# - a default: the default value of an attribute when an instance is created +# - a void flag: the attribute can be authorized to be None or not using this +# flag. Setting an attribute to a None value while the flag is not set to +# True raises an exception. By default, a None value is not allowed. +# +# These properties are dictionnaries mapping the attribute name to its +# associated value for the property. +# \n A typical usage is to derived this class in a specialized form where the +# attributes names and there properties are defined in the constructor. See +# use cases at the end of this file. +# \ingroup datamodeler class DataModeler: """ This class is a placeholder for modeling data. An object based on this class @@ -85,6 +108,7 @@ class DataModeler: for name in self._defaultmap.keys(): self.__setattr__(name,self._defaultmap[name]) + ## %A None argument means that no entry is created in the associated maps. def addAttribute(self, name, type=None, range=None, default=None, void=None): """ A None argument means that no entry is created in the associated maps. diff --git a/src/KERNEL_PY/kernel/deprecation.py b/src/KERNEL_PY/kernel/deprecation.py index 46d431b12..588b41625 100644 --- a/src/KERNEL_PY/kernel/deprecation.py +++ b/src/KERNEL_PY/kernel/deprecation.py @@ -18,6 +18,21 @@ # # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com # + +## \defgroup deprecation deprecation +# \{ +# \details +# This module provides several functions to indicate the deprecation of a +# module, a method or a function. +# \code +# from salome.kernel.deprecation import deprecated +# deprecated("Deprecated since version 6.3.0. Consider replacement with +# newFunction()") +# def oldFunction(): +# ... +# \endcode +# \} + """ This module provides several functions to indicate the deprecation of a module, a method or a function. @@ -63,6 +78,13 @@ def __deprecated_with_msg(func, msg): return func(*args, **kwargs) return new_func +## This is a decorator which can be used to mark functions +# as deprecated. It will result in a warning being emitted +# when the function is used. The message in parameter will +# be displayed and should indicate how this function can be +# replaced. If the terminal can display colors, the warning +# messages will appear in blue. +# \ingroup deprecation def deprecated(msg = msg_seedoc): """ This is a decorator which can be used to mark functions @@ -83,6 +105,13 @@ def deprecated(msg = msg_seedoc): return g return make_dep +## This function can be used to mark a module as deprecated. +# It must be called explicitly at the beginning of the deprecated +# module. It will result in a warning being emitted. The message +# in parameter will be displayed and should indicate how this +# module can be replaced. If the terminal can display colors, +# the warning messages will appear in blue. +# \ingroup deprecation def deprecated_module(msg = msg_seedoc): """ This function can be used to mark a module as deprecated. @@ -102,6 +131,11 @@ def deprecated_module(msg = msg_seedoc): stacklevel = 5 ) +## Determine if the calling code is ultimately called by sphinx to generate +# documentation. The result can be used to conditionally inhibit the +# decorators or some Salome-related imports that fail when called outside +# Salome. +# \ingroup deprecation def is_called_by_sphinx(): """ Determine if the calling code is ultimately called by sphinx to generate diff --git a/src/KERNEL_PY/kernel/diclookup.py b/src/KERNEL_PY/kernel/diclookup.py index 9bbbe2f84..140d13ad8 100644 --- a/src/KERNEL_PY/kernel/diclookup.py +++ b/src/KERNEL_PY/kernel/diclookup.py @@ -21,6 +21,11 @@ # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com # +## \defgroup diclookup diclookup +# \{ +# \details Smart dictionnary with key/value lookup +# \} + __author__="gboulant" __date__ ="$21 mai 2010 18:00:23$" @@ -29,26 +34,36 @@ __date__ ="$21 mai 2010 18:00:23$" # using named functions or a class # tested with Python25 by Ene Uran 01/19/2008 +## return the key of dictionary dic given the value +# \ingroup diclookup def find_key(dic, val): """return the key of dictionary dic given the value""" return [k for k, v in dic.iteritems() if v == val][0] +## return the value of dictionary dic given the key +# \ingroup diclookup def find_value(dic, key): """return the value of dictionary dic given the key""" return dic[key] +## a dictionary which can lookup value by key, or keys by value +# \ingroup diclookup class Lookup(dict): """ a dictionary which can lookup value by key, or keys by value """ + ## items can be a list of pair_lists or a dictionary def __init__(self, items=[]): """items can be a list of pair_lists or a dictionary""" dict.__init__(self, items) + ## find the key(s) as a list given a value def get_keys(self, value): """find the key(s) as a list given a value""" return [item[0] for item in self.items() if item[1] == value] + ## find the key associated to the given a value. If several keys exist, + # only the first is given. To get the whole list, use get_keys instead. def get_key(self, value): """ find the key associated to the given a value. If several keys exist, @@ -59,6 +74,7 @@ class Lookup(dict): return None return list[0] + ## find the value given a key def get_value(self, key): """find the value given a key""" return self[key] diff --git a/src/KERNEL_PY/kernel/enumerate.py b/src/KERNEL_PY/kernel/enumerate.py index fd92c8ebb..97500ab30 100644 --- a/src/KERNEL_PY/kernel/enumerate.py +++ b/src/KERNEL_PY/kernel/enumerate.py @@ -18,15 +18,29 @@ # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com # +## \defgroup enumerate enumerate +# \{ +# \details Emulates a C-like enum for python +# \} + __author__ = "gboulant" __date__ = "$1 avr. 2010 09:08:02$" +## This class emulates a C-like enum for python. It is initialized with a list +# of strings to be used as the enum symbolic keys. The enum values are automatically +# generated as sequencing integer starting at the specified offset value. +# \ingroup enumerate class Enumerate(object): """ This class emulates a C-like enum for python. It is initialized with a list of strings to be used as the enum symbolic keys. The enum values are automatically generated as sequencing integer starting at the specified offset value. """ + + ## Canonical constructor. + # \param keys a list of string to be used as the enum symbolic keys. The enum values + # are automatically generated as a sequence of integers starting at the specified + # offset value. def __init__(self, keys, offset=0): """ Canonical constructor @@ -40,6 +54,8 @@ class Enumerate(object): setattr(self, key, value) self._dict_keynumbers[key] = value + ## Return true if this enumerate contains the specified key string + # \param key a key string to test def contains(self, key): """ Return true if this enumerate contains the specified key string @@ -47,6 +63,9 @@ class Enumerate(object): """ return (key in self._dict_keynumbers.keys()) + ## Returns true if the specified integer value is defined as an identifier + # in this enumarate. + # \param value a value to test def isValid(self, value): """ Returns true if the specified integer value is defined as an identifier @@ -55,6 +74,7 @@ class Enumerate(object): """ return (value in self._dict_keynumbers.values()) + ## Returns the list of keys in this enumerate. def listkeys(self): """ Returns the list of keys in this enumerate. @@ -63,6 +83,7 @@ class Enumerate(object): list.sort() return list + ## Returns the list of values specified to initiate this enumerate. def listvalues(self): """ Returns the list of values specified to initiate this enumerate. @@ -71,6 +92,8 @@ class Enumerate(object): list.sort() return list + ## Returns the symbolic key string associated to the specified identifier value. + # \param value an integer value whose associated key string is requested. def keyOf(self, value): """ Returns the symbolic key string associated to the specified identifier diff --git a/src/KERNEL_PY/kernel/logger.py b/src/KERNEL_PY/kernel/logger.py index ed9d50014..cc91cc710 100644 --- a/src/KERNEL_PY/kernel/logger.py +++ b/src/KERNEL_PY/kernel/logger.py @@ -26,6 +26,13 @@ # Copyright : EDF 2001-2009 # $Header$ #============================================================================= + +## \defgroup logger logger +# \{ +# \details +# This module defines a class which provides logging facility in Salome. +# \} + """ This module defines a class which provides logging facility in Salome: """ @@ -37,6 +44,42 @@ from salome.kernel.deprecation import deprecated from salome.kernel import termcolor import salome.kernel.logconfig +## This class formats and displays log messages in Salome environment. It +# inherits \b logging.Logger class defined in \b logging module from Python +# library, so all methods from \b logging.Logger can be used here. +# The format of the traces is: +# LEVEL[keyword] : Message +# +# ,where \em LEVEL is the level of the message (\em DEBUG, \em INFO, etc.), +# \em keyword is the name of the logger, and \em Message is the message to log. +# +# When creating a new Logger object, the parameter \em keyword defines the +# name of the logger, \em level defines the logging level (default is +# \b logging.DEBUG if KERNEL module is configured with --enable-debug option +# or \b logging.WARNING otherwise), and \em color defines the color +# of the log messages for this logger (log messages will appear in color +# only when displayed on color - capable ASCII terminals). See module +# \ref termcolor "salome.kernel.termcolor" for the color constants. +# +# By default, log messages will be displayed only on standard output. They +# can also be recorded in a file (see method setLogFile()). For now, +# the CORBA-based logging facility can not be used through this class. +# +# A source filename \em sourceFileName can be defined. If this argument is +# specified, then the \em keyword is modified to the basename of the +# \em sourceFileName +# +# Basic usage:: +# \code +# from salome.kernel.logger import Logger +# log = Logger("Test") +# log.debug("Debug message") +# log.info("Information message") +# log.warning("Warning message") +# log.error("Error message") +# log.critical("Fatal error message") +# \endcode +# \ingroup logger class Logger(logging.Logger): """ This class formats and displays log messages in Salome environment. It @@ -94,6 +137,8 @@ class Logger(logging.Logger): self.addHandler(self._stdoutHandler) self._fileHandler = None + ## Log all messages, including DEBUG level messages (equivalent to + # setLevel(logging.DEBUG)). def showDebug(self): """ Log all messages, including DEBUG level messages (equivalent to @@ -101,6 +146,8 @@ class Logger(logging.Logger): """ self.setLevel(logging.DEBUG) + ## Define a log file to record the log messages (in addition to the + # standard output). def setLogFile(self, logFilename): """ Define a log file to record the log messages (in addition to the @@ -112,6 +159,8 @@ class Logger(logging.Logger): self._fileHandler.setFormatter(self._baseFormatter) self.addHandler(self._fileHandler) + ## Set the color of log messages on color-capable terminals. If \em color + # is \b None, the default color will be used. def setColor(self, color): """ Set the color of log messages on color-capable terminals. If `color` @@ -127,6 +176,7 @@ class Logger(logging.Logger): stdoutFormatter = logging.Formatter(format) self._stdoutHandler.setFormatter(stdoutFormatter) + ## Close the log file. def closeLogFile(self): """Close the log file.""" if self._fileHandler is not None: @@ -134,6 +184,7 @@ class Logger(logging.Logger): self._fileHandler.close() self._fileHandler = None + ## Hide DEBUG level messages (equivalent to setLevel(logging.INFO)). def hideDebug(self): """ Hide DEBUG level messages (equivalent to ``setLevel(logging.INFO)``). @@ -142,6 +193,9 @@ class Logger(logging.Logger): @deprecated("Deprecated since version 5.1.5. Please replace with " "Logger.critical(message)") + + ## Log a message with CRITICAL level. This method only exists for + # backward compatibility and is equivalent to \b critical(message). def fatal(self, message): """ Log a message with CRITICAL level. This method only exists for @@ -149,7 +203,9 @@ class Logger(logging.Logger): """ self.critical(message) - +## This utility class allows to log messages to a stream with no \b flush +# method. This is useful to send log messages to \b PyOut objects. +# \ingroup logger class _UnFlushableLogStream: """ This utility class allows to log messages to a stream with no `flush` @@ -165,7 +221,11 @@ class _UnFlushableLogStream: def flush(self): pass - +## This class extends Logger class and adds exception information +# when DEBUG messages are recorded. It exists mainly for backward +# compatibility, as the same thing can be done by calling +# Logger.debug(message, exc_info = True) . +# \ingroup logger class ExtLogger(Logger): """ This class extends :class:`Logger` class and adds exception information @@ -181,6 +241,8 @@ class ExtLogger(Logger): color = None, sourceFileName=None): Logger.__init__(self, keyword, level, color, sourceFileName) + ## Log a DEBUG message with exception information (equivalent to + # Logger.debug(message, exc_info = True) ). def debug( self, message ): """ Log a DEBUG message with exception information (equivalent to @@ -188,7 +250,8 @@ class ExtLogger(Logger): """ Logger.debug(self, message, exc_info = True) - +## Test function for logger module +# \ingroup logger def TEST_Logger(): """Test function for logger module""" log = Logger("TST") diff --git a/src/KERNEL_PY/kernel/parametric/__init__.py b/src/KERNEL_PY/kernel/parametric/__init__.py index b167b53f1..cb5350db2 100644 --- a/src/KERNEL_PY/kernel/parametric/__init__.py +++ b/src/KERNEL_PY/kernel/parametric/__init__.py @@ -17,3 +17,10 @@ # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com # +## \defgroup salome_kernel_parametric salome.kernel.parametric +# \{ +# \details Package for parametric studies +# \defgroup study_exchange_vars +# \defgroup compo_utils +# \defgroup pyscript_utils +# \} diff --git a/src/KERNEL_PY/kernel/parametric/compo_utils.py b/src/KERNEL_PY/kernel/parametric/compo_utils.py index c19cc7237..d3af77e75 100644 --- a/src/KERNEL_PY/kernel/parametric/compo_utils.py +++ b/src/KERNEL_PY/kernel/parametric/compo_utils.py @@ -17,6 +17,16 @@ # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com # +## \defgroup compo_utils compo_utils +# \{ +# \details +# This module provides utility functions for the computation codes intended for +# use in parametric studies. The computation codes must be implemented as %SALOME +# components to use these functions. If the computation code is implemented as a +# Python script or function, use module +# salome.kernel.parametric.compo_utils instead. +# \} + """ This module provides utility functions for the computation codes intended for use in parametric studies. The computation codes must be implemented as SALOME @@ -27,6 +37,17 @@ Python script or function, use module import SALOME_TYPES +## This function returns a dictionary containing the input values to be used +# in the computation code. +# +# \param deterministic_dict (dict) dictionary containing the fixed values (i.e. +# non-parametric). This dictionary can be empty if all variables are parametric. +# +# \param parametric_input (SALOME_TYPES/ParametricInput) structure containing +# the description and values of the parametric variables. +# +# \return a dictionary containing the input values for the computation code. +# \ingroup compo_utils def create_input_dict(deterministic_dict, parametric_input): """ This function returns a dictionary containing the input values to be used @@ -55,6 +76,18 @@ def create_input_dict(deterministic_dict, parametric_input): return input_dict +## This function returns a structure describing the output of the computation +# code in parametric studies. +# +# \param output_dict (dict) dictionary containing the output values of the +# computation code (the keys are the variable names, the values are the variable values). +# +# \param parametric_input (SALOME_TYPES/ParametricInput) structure containing +# the description and values of the parametric variables. +# +# \return a structure of type SALOME_TYPES/ParametricOutput containing the +# output of the computation code. +# \ingroup compo_utils def create_normal_parametric_output(output_dict, parametric_input): """ This function returns a structure describing the output of the computation @@ -80,6 +113,13 @@ def create_normal_parametric_output(output_dict, parametric_input): returnCode = 0, errorMessage = "") +## This function returns a structure describing the output of the computation +# code in parametric studies in case of error. +# +# \param error_message (string) the error message. +# +# \return a structure of type SALOME_TYPES/ParametricOutput describing the error. +# \ingroup compo_utils def create_error_parametric_output(error_message): """ This function returns a structure describing the output of the computation diff --git a/src/KERNEL_PY/kernel/parametric/pyscript_utils.py b/src/KERNEL_PY/kernel/parametric/pyscript_utils.py index beb88b6db..98ffe9eda 100644 --- a/src/KERNEL_PY/kernel/parametric/pyscript_utils.py +++ b/src/KERNEL_PY/kernel/parametric/pyscript_utils.py @@ -17,6 +17,16 @@ # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com # +## \defgroup pyscript_utils pyscript_utils +# \{ +# \details +# This module provides utility functions for the computation codes intended for +# use in parametric studies. The computation codes must be implemented as a +# Python script or function to use these functions. If the computation code is +# implemented as a %SALOME component, use module +# salome.kernel.parametric.compo_utils instead. +# \} + """ This module provides utility functions for the computation codes intended for use in parametric studies. The computation codes must be implemented as a @@ -25,6 +35,17 @@ implemented as a SALOME component, use module :mod:`salome.kernel.parametric.compo_utils` instead. """ +## This function returns a dictionary containing the input values to be used +# in the computation code. +# +# \param deterministic_dict (dict) dictionary containing the fixed values (i.e. +# non-parametric). This dictionary can be empty if all variables are parametric. +# +# \param parametric_input (dict) dictionary containing the description and values +# of the parametric variables. +# +# \return a dictionary containing the input values for the computation code. +# \ingroup pyscript_utils def create_input_dict(deterministic_dict, parametric_input): """ This function returns a dictionary containing the input values to be used @@ -53,6 +74,19 @@ def create_input_dict(deterministic_dict, parametric_input): return input_dict +## This function returns a dictionary describing the output of the +# computation code in parametric studies. +# +# \param output_dict (dict) dictionary containing the output values of the +# computation code (the keys are the variable names, the +# values are the variable values). +# +# \param parametric_input (dict) dictionary containing the description and values +# of the parametric variables. +# +# \return a dictionary containing the representation of the output of the +# computation code. +# \ingroup pyscript_utils def create_normal_parametric_output(output_dict, parametric_input): """ This function returns a dictionary describing the output of the @@ -78,6 +112,13 @@ def create_normal_parametric_output(output_dict, parametric_input): "returnCode" : 0, "errorMessage" : ""} +## This function returns a dictionary describing the output of the +# computation code in parametric studies in case of error. +# +# \param error_message (string) the error message. +# +# \return a dictionary describing the error. +# \ingroup pyscript_utils def create_error_parametric_output(error_message): """ This function returns a dictionary describing the output of the diff --git a/src/KERNEL_PY/kernel/parametric/study_exchange_vars.py b/src/KERNEL_PY/kernel/parametric/study_exchange_vars.py index 4b15c1695..e30a33949 100644 --- a/src/KERNEL_PY/kernel/parametric/study_exchange_vars.py +++ b/src/KERNEL_PY/kernel/parametric/study_exchange_vars.py @@ -17,6 +17,15 @@ # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com # +## \defgroup study_exchange_vars study_exchange_vars +# \{ +# \details +# This module provides classes and functions to handle "Exchange Variables", +# i.e. description of variables to be exchanged between a supervision code and a +# computation code. These Exchange Variables can be stored in a SObject in +# Salome study. +# \} + """ This module provides classes and functions to handle "Exchange Variables", i.e. description of variables to be exchanged between a supervision code and a @@ -32,6 +41,9 @@ INPUT_VAR_NAMES = "ExchangeVariables.InputVarNames" OUTPUT_VAR_NAMES = "ExchangeVariables.OutputVarNames" REF_ENTRY = "ExchangeVariables.RefEntry" +## This class describes a single variable. For now, it is only described by +# its name. Other attributes are reserved for future use. +# \ingroup study_exchange_vars class Variable: """ This class describes a single variable. For now, it is only described by @@ -48,7 +60,21 @@ class Variable: self.maxValue = maxValue self.initialValue = initialValue - +## This class describes "Exchange Variables", i.e. a structure containing all +# the necessary information to exchange variables between a supervision code +# and a computation code. +# +# \param inputVarList This instance attribute is a list of \b Variable objects, +# describing the input variables for the computation code. +# +# \param outputVarList This instance attribute is a list of \b Variable objects, +# describing the output variables for the computation code. +# +# \param refEntry This instance attribute is optional and can be used to store a +# reference to a Salome entry containing an "Exchange Variable" SObject +# that was used to build this one (when the current object has been built +# by selecting variables of interest in a list of potential variables). +# \ingroup study_exchange_vars class ExchangeVariables: """ This class describes "Exchange Variables", i.e. a structure containing all @@ -80,6 +106,9 @@ class ExchangeVariables: self.outputVarList = outputVarList self.refEntry = refEntry + ## Save this object to an XML file. + # + # \param filepath (string) path of the XML file. def saveToXmlFile(self, filepath): """ Save this object to an XML file. @@ -107,6 +136,21 @@ class ExchangeVariables: f.write(doc.toprettyxml(indent = " ")) f.close() +## Create a SObject to store an \b ExchangeVariables instance. +# +# \param fatherSobj (SObject) parent of the SObject to create. +# +# \param exchangeVariables (ExchangeVariables) \b ExchangeVariables instance to store in +# Salome study. +# +# \param name (string) name of the SObject to create. +# +# \param icon (string) icon of the SObject to create. +# +# \param typeId (integer) type of the SObject to create. +# +# \return the newly created SObject. +# \ingroup study_exchange_vars def createSObjectForExchangeVariables(fatherSobj, exchangeVariables, name = DEFAULT_NAME, icon = None, typeId = None): @@ -140,6 +184,13 @@ def createSObjectForExchangeVariables(fatherSobj, exchangeVariables, typeId = typeId) _setSObjectForExchangeVariables(editor, sobj, exchangeVariables) +## Update an existing SObject storing an \b ExchangeVariables instance. +# +# \param sobj (SObject) the SObject to update. +# +# See \b createSObjectForExchangeVariables() for the description of the +# other parameters. +# \ingroup study_exchange_vars def updateSObjectForExchangeVariables(sobj, exchangeVariables, name = DEFAULT_NAME, icon = None, typeId = None): @@ -168,6 +219,13 @@ def _setSObjectForExchangeVariables(editor, sobj, exchangeVariables): if exchangeVariables.refEntry is not None: attr.SetString(REF_ENTRY, exchangeVariables.refEntry) +## Get an \b ExchangeVariables instance from a SObject that stores it. +# +# \param sobj (SObject) the SObject from which to read the \b ExchangeVariables +# instance. +# +# \return the newly created \b ExchangeVariables instance. +# \ingroup study_exchange_vars def getExchangeVariablesFromSObject(sobj): """ Get an :class:`ExchangeVariables` instance from a SObject that stores it. @@ -190,6 +248,12 @@ def getExchangeVariablesFromSObject(sobj): [Variable(name) for name in attr.GetStrArray(OUTPUT_VAR_NAMES)], refEntry) +## Load an \b ExchangeVariables instance from an XML file. +# +# \param filepath (string) path of the XML file to load. +# +# \return the newly created \b ExchangeVariables instance. +# \ingroup study_exchange_vars def loadExchangeVariablesFromXmlFile(filepath): """ Load an :class:`ExchangeVariables` instance from an XML file. diff --git a/src/KERNEL_PY/kernel/pyunittester.py b/src/KERNEL_PY/kernel/pyunittester.py index c99c5bb6c..6c8109951 100644 --- a/src/KERNEL_PY/kernel/pyunittester.py +++ b/src/KERNEL_PY/kernel/pyunittester.py @@ -18,6 +18,11 @@ # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com # +## \defgroup pyunittester pyunittester +# \{ +# \details Simple wrapper of the pyunit framework +# \} + import sys from salome.kernel import termcolor def printfile(filename): @@ -36,10 +41,12 @@ import unittest from unittest import TestCase from uiexception import DevelException +## This class is a simple wrapper of the pyunit framework. +# \ingroup pyunittester class PyUnitTester(): - ''' + """ This class is a simple wrapper of the pyunit framework. - ''' + """ def __init__(self): self.__listTestSuite=[] self.setLogFilename("testlog.txt") @@ -75,6 +82,10 @@ class PyUnitTester(): def printreport(self): printfile(self.__logfilename) +## This can be used to just execute a test function that is +# considered as OK simply if no exception is raised (can be test by +# an assertTrue). +# \ingroup pyunittester def execAndConvertExceptionToBoolean(function): """ This can be used to just execute a test function that is @@ -92,6 +103,8 @@ def execAndConvertExceptionToBoolean(function): # Simple helper function for most cases where there is only one # TestCase classe. +## Run the test suite provided by the specified TestCase class. +# \ingroup pyunittester def run(testCaseClass): """ Run the test suite provided by the specified TestCase class. diff --git a/src/KERNEL_PY/kernel/services.py b/src/KERNEL_PY/kernel/services.py index 37b38964f..0d975396e 100644 --- a/src/KERNEL_PY/kernel/services.py +++ b/src/KERNEL_PY/kernel/services.py @@ -20,6 +20,11 @@ # Author: Guillaume Boulant (EDF/R&D) +## \defgroup service service +# \{ +# \details Helper for using %SALOME kernel services +# \} + # # WARNING: development notes # @@ -64,26 +69,27 @@ if not is_called_by_sphinx() and salome.lcc is None: # ============================================================================== # +## Get a %SALOME CORBA component from its name +# \param componentName is the name of the component as declared in the XML +# %SALOME catalog. %A loadable library with name libEngine.so +# is supposed to be reachable. This library is supposed to provide a +# factory function with the prototype: # -# componentName is the name of the component as declared in the XML -# SALOME catalog. A loadable library with name libEngine.so -# is supposed to be reachable. This library is supposed to provide a -# factory function with the prototype: -# -# PortableServer::ObjectId * Engine_factory( -# CORBA::ORB_ptr orb, -# PortableServer::POA_ptr poa, -# PortableServer::ObjectId * contId, -# const char *instanceName, -# const char *interfaceName); +# \code +# PortableServer::ObjectId * Engine_factory( CORBA::ORB_ptr orb, +# PortableServer::POA_ptr poa, +# PortableServer::ObjectId* contId, +# const char *instanceName, +# const char *interfaceName ); +# \endcode # -# corbaModule is the name of the IDL module that contains the -# definition of the interface of the component. This name corresponds -# to the namespace of the servant classes. -# -# containerType specified the container in which the servants are -# executed. +# \param corbaModule is the name of the IDL module that contains the +# definition of the interface of the component. This name corresponds +# to the namespace of the servant classes. # +# \param containerType specified the container in which the servants are +# executed. +# \ingroup service def getComponent(componentName = "SalomeTestComponent", corbaModule = "Engines", containerType = "FactoryServer"): @@ -102,6 +108,10 @@ def getComponent(componentName = "SalomeTestComponent", # is to use the module catalog. Here, we just use the catalog to get # the list of components defined in the current session. import SALOME_ModuleCatalog + +## Get the list of names of all %SALOME componenents register in +# the catalog. +# \ingroup service def getComponentList(): """ Get the list of names of all SALOME componenents register in @@ -113,11 +123,17 @@ def getComponentList(): raise RuntimeError, "Can't accesss module catalog" return catalog.GetComponentList() +## Get a study manager to create and manage %SALOME studies +# \ingroup service def getStudyManager(): """Get a study manager to create and manage SALOME studies""" return salome.myStudyManager import SALOMEDS +## Get a study manager to create and manage SALOME studies. +# \warning you should use instead the variable salome.myStudyManager. +# This function is given for illustration of usage of the naming service +# \ingroup service def __getStudyManager_demo(): """ Get a study manager to create and manage SALOME studies. WARN: you diff --git a/src/KERNEL_PY/kernel/studyedit.py b/src/KERNEL_PY/kernel/studyedit.py index d7448b419..c11a8b33b 100644 --- a/src/KERNEL_PY/kernel/studyedit.py +++ b/src/KERNEL_PY/kernel/studyedit.py @@ -18,6 +18,14 @@ # # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com # + +## \defgroup studyedit studyedit +# \{ +# \details +# This module provides a new class \bStudyEditor to complement \bStudy +# and \bStudyBuilder classes. +# \} + """ This module provides a new class :class:`StudyEditor` to complement :class:`Study` and :class:`StudyBuilder` classes. @@ -33,6 +41,10 @@ logger = Logger("salome.kernel.studyedit", color = termcolor.PURPLE) _editors = {} _DEFAULT_CONTAINER = "FactoryServer" +## Return the ID of the active study. In GUI mode, this function is equivalent +# to salome.sg.getActiveStudyId(). Outside GUI, it returns salome.myStudyId +# variable. +# \ingroup studyedit def getActiveStudyId(): """ Return the ID of the active study. In GUI mode, this function is equivalent @@ -60,6 +72,9 @@ def getStudyIdFromStudy(study): studyId = study._get_StudyId() return studyId +## Return a \b StudyEditor instance to edit the study with ID studyId. +# If \b studyId is \b None, return an editor for the current study. +# \ingroup studyedit def getStudyEditor(studyId = None): """ Return a :class:`StudyEditor` instance to edit the study with ID @@ -72,6 +87,24 @@ def getStudyEditor(studyId = None): _editors[studyId] = StudyEditor(studyId) return _editors[studyId] +## This class provides utility methods to complement \b Study and +# \b StudyBuilder classes. Those methods may be moved in those classes +# in the future. The parameter \b studyId defines the ID of the study to +# edit. If it is \em None, the edited study will be the current study. +# The preferred way to get a StudyEditor object is through the method +# \b getStudyEditor which allows to reuse existing instances. +# +# \param studyId This instance attribute contains the ID of the edited study. +# This attribute should not be modified. +# +# \param study This instance attribute contains the underlying \b Study object. +# It can be used to access the study but the attribute itself should not +# be modified. +# +# \param builder This instance attribute contains the underlying \b StudyBuilder +# object. It can be used to edit the study but the attribute itself +# should not be modified. +# \ingroup studyedit class StudyEditor: """ This class provides utility methods to complement :class:`Study` and @@ -110,6 +143,27 @@ class StudyEditor: "Study %d doesn't exist" % studyId) self.builder = self.study.NewBuilder() + ## Find a component corresponding to the Salome module \b moduleName in + # the study. If none is found, create a new component and associate it + # with the corresponding engine (i.e. the engine named \b moduleName). + # Note that in Salome 5, the module name and engine name must be + # identical (every module must provide an engine with the same name). + # In Salome 6 it will be possible to define a different name for the + # engine. + # + # \param moduleName (string) name of the module corresponding to the component + # (the module name is the string value in the + # attribute "AttributeComment" of the component) + # + # \param componentName (string) name of the new component if created. + # If \b None, use \b moduleName instead. + # + # \param icon (string) icon for the new component (attribute "AttributePixMap"). + # + # \param containerName (string) name of the container in which the engine should be + # loaded. + # + # \return the SComponent found or created. def findOrCreateComponent(self, moduleName, componentName = None, icon = None, containerName = _DEFAULT_CONTAINER): """ @@ -175,6 +229,9 @@ class StudyEditor: return sComponent + ## Load the engine corresponding to \b sComponent in the container + # \b containerName, associate the engine with the component and load the + # CORBA objects of this component in the study. def loadComponentEngine(self, sComponent, containerName = _DEFAULT_CONTAINER): """ @@ -195,6 +252,8 @@ class StudyEditor: containerName)) self.builder.LoadWith(sComponent, engine) + ## Get the CORBA object associated with the SObject \b item, eventually by + # first loading it with the corresponding engine. def getOrLoadObject(self, item): """ Get the CORBA object associated with the SObject `item`, eventually by @@ -207,6 +266,11 @@ class StudyEditor: object = item.GetObject() return object + ## Find an object under \b fatherItem in the study with the given + # attributes. Return the first one found if at least one exists, + # otherwise create a new one with the given attributes and return it. + # + # See \b setItem() for the description of the parameters. def findOrCreateItem(self, fatherItem, name, fileType = None, fileName = None, comment = None, icon = None, IOR = None, typeId = None): @@ -224,6 +288,14 @@ class StudyEditor: comment, icon, IOR, typeId) return sObject + ## Find an item with given attributes under \b fatherItem in the study. If + # none is found, return \b None. If several items correspond to + # the parameters, only the first one is returned. The search is made + # only on given parameters (i.e. not \b None). To look explicitly + # for an empty attribute, use an empty string in the corresponding + # parameter. + # + # See \b setItem() for the description of the parameters. def findItem(self, fatherItem, name = None, fileType = None, fileName = None, comment = None, icon = None, IOR = None, typeId = None): @@ -257,6 +329,15 @@ class StudyEditor: childIterator.Next() return foundItem + ## Create a new object named \b name under \b fatherItem in the study, with + # the given attributes. If an object named \b name already exists under + # the father object, the new object is created with a new name \b name_X + # where X is the first available index. + # + # param fatherItem (SObject) item under which the new item will be added. + # \return new SObject created in the study. + # + # See \b setItem() for the description of the other parameters. def createItem(self, fatherItem, name, fileType = None, fileName = None, comment = None, icon = None, IOR = None, typeId = None): """ @@ -310,6 +391,26 @@ class StudyEditor: return aSObject + ## Modify the attributes of an item in the study. Unspecified attributes + # (i.e. those set to \b None) are left unchanged. + # + # \param item (SObject) item to modify. + # + # \param name (string) item name (attribute \b AttributeName). + # + # \param fileType (string) item file type (attribute \b AttributeFileType). + # + # \param fileName (string) item file name (attribute \b AttributeExternalFileDef). + # + # \param comment (string) item comment (attribute \b AttributeComment). Note that + # this attribute will appear in the \b Value column in the object browser. + # + # \param icon (string) item icon name (attribute \b AttributePixMap). + # + # \param IOR (string) IOR of a CORBA object associated with the item + # (attribute \b AttributeIOR). + # + # \param typeId (integer) item type (attribute \b AttributeLocalID). def setItem(self, item, name = None, fileType = None, fileName = None, comment = None, icon = None, IOR = None, typeId = None): """ @@ -364,6 +465,15 @@ class StudyEditor: if typeId is not None: self.setTypeId(item, typeId) + ## Remove the given item from the study. Note that the items are never + # really deleted. They just don't appear in the study anymore. + # + # \param item (SObject) the item to be removed + # + # \param withChildren (boolean) if \b True, also remove the children of item + # + # \return \b True if the item was removed successfully, or + # \b False if an error happened. def removeItem(self, item, withChildren = False ): """ Remove the given item from the study. Note that the items are never @@ -390,6 +500,18 @@ class StudyEditor: ok = False return ok + ## Find an item tagged \b tag under \b fatherItem in the study tree or + # create it if there is none, then set its attributes. + # + # \param fatherItem (SObject) item under which the tagged item will be looked for + # and eventually created. + # + # \param tag integer) tag of the item to look for. + # + # \return the SObject at \b tag if found or created successfully, or + # \b None if an error happened. + # + # See \b setItem() for the description of the other parameters. def setItemAtTag(self, fatherItem, tag, name = None, fileType = None, fileName = None, comment = None, icon = None, IOR = None, typeId = None): @@ -416,6 +538,8 @@ class StudyEditor: IOR, typeId) return sObj + ## Return the value of the attribute named \b attributeName on the object + # sObject, or \b default if the attribute doesn't exist. def getAttributeValue(self, sObject, attributeName, default = None): """ Return the value of the attribute named `attributeName` on the object @@ -427,6 +551,8 @@ class StudyEditor: value = attr.Value() return value + ## Set the value of the attribute named \b attributeName on the object + # sObject to the value \b attributeValue. def setAttributeValue(self, sObject, attributeName, attributeValue): """ Set the value of the attribute named `attributeName` on the object @@ -435,6 +561,8 @@ class StudyEditor: attr = self.builder.FindOrCreateAttribute(sObject, attributeName) attr.SetValue(attributeValue) + ## Return the value of the attribute "AttributeLocalID" of the object + # sObject, or \b None if it is not set. def getTypeId(self, sObject): """ Return the value of the attribute "AttributeLocalID" of the object @@ -442,6 +570,8 @@ class StudyEditor: """ return self.getAttributeValue(sObject, "AttributeLocalID") + ## Set the attribute "AttributeLocalID" of the object \b sObject to the + # value \b value. def setTypeId(self, sObject, value): """ Set the attribute "AttributeLocalID" of the object `sObject` to the @@ -449,6 +579,8 @@ class StudyEditor: """ self.setAttributeValue(sObject, "AttributeLocalID", value) + ## Return the value of the attribute "AttributeFileType" of the object + # sObject, or an empty string if it is not set. def getFileType(self, sObject): """ Return the value of the attribute "AttributeFileType" of the object @@ -456,6 +588,8 @@ class StudyEditor: """ return self.getAttributeValue(sObject, "AttributeFileType", "") + ## Set the attribute "AttributeFileType" of the object sObject to the + # value value. def setFileType(self, sObject, value): """ Set the attribute "AttributeFileType" of the object `sObject` to the @@ -464,6 +598,8 @@ class StudyEditor: # Explicit cast is necessary for unicode to string conversion self.setAttributeValue(sObject, "AttributeFileType", str(value)) + ## Return the value of the attribute "AttributeExternalFileDef" of the + # object sObject, or an empty string if it is not set. def getFileName(self, sObject): """ Return the value of the attribute "AttributeExternalFileDef" of the @@ -471,6 +607,8 @@ class StudyEditor: """ return self.getAttributeValue(sObject, "AttributeExternalFileDef", "") + ## Set the attribute "AttributeExternalFileDef" of the object sObject + # to the value value. def setFileName(self, sObject, value): """ Set the attribute "AttributeExternalFileDef" of the object `sObject` @@ -480,6 +618,8 @@ class StudyEditor: self.setAttributeValue(sObject, "AttributeExternalFileDef", str(value)) + ## Return the value of the attribute "AttributePixMap" of the object + # sObject, or an empty string if it is not set. def getIcon(self, sObject): """ Return the value of the attribute "AttributePixMap" of the object @@ -491,6 +631,8 @@ class StudyEditor: value = attr.GetPixMap() return value + ## Set the attribute "AttributePixMap" of the object sObject to the + # value value. def setIcon(self, sObject, value): """ Set the attribute "AttributePixMap" of the object `sObject` to the diff --git a/src/KERNEL_PY/kernel/termcolor.py b/src/KERNEL_PY/kernel/termcolor.py index 86257d2be..3d1f8c495 100644 --- a/src/KERNEL_PY/kernel/termcolor.py +++ b/src/KERNEL_PY/kernel/termcolor.py @@ -21,6 +21,32 @@ # Author : Renaud Barate (EDF R&D) # Date : August 2009 # + +## \defgroup termcolor termcolor +# \{ +# \details +# This module provides utility functions to display colored text in the +# terminal. It is based on ISO 6429 standard that defines control codes to +# change characters representation in color-capable ASCII terminals. +# +# In this module, colors are represented as lists of codes, so they can be added +# to obtain special effects (e.g. RED + GREEN_BG to display red text on green +# background). Several constants are defined for the most usual codes to +# facilitate the use of colors, but it is also possible to define colors +# directly from the corresponding code from ISO 6429 standard. In fact it is +# even necessary for less usual codes that don't have an associated constant +# (e.g. PURPLE + ['09'] can be used to display a crossed-out purple text). +# +# \code +# import sys +# from salome.kernel import termcolor +# if termcolor.canDisplayColor(sys.stdout): +# print termcolor.makeColoredMessage("Hello world!", termcolor.BLUE) +# else: +# print "Hello world!" +# \endcode +# \} + """ This module provides utility functions to display colored text in the terminal. It is based on ISO 6429 standard that defines control codes to @@ -46,70 +72,128 @@ Example:: """ # Constants for color codes +## Default color for the terminal +# \ingroup termcolor DEFAULT = ['00'] """Default color for the terminal""" +## Bold text and brighter colors +# \ingroup termcolor BOLD = ['01'] """Bold text and brighter colors""" +## Underlined text +# \ingroup termcolor UNDERLINED = ['04'] """Underlined text""" +## Black foreground +# \ingroup termcolor BLACK_FG = ['30'] """Black foreground""" +## Red foreground +# \ingroup termcolor RED_FG = ['31'] """Red foreground""" +## Green foreground +# \ingroup termcolor GREEN_FG = ['32'] """Green foreground""" +## Yellow foreground +# \ingroup termcolor YELLOW_FG = ['33'] """Yellow foreground""" +## Blue foreground +# \ingroup termcolor BLUE_FG = ['34'] """Blue foreground""" +## Purple foreground +# \ingroup termcolor PURPLE_FG = ['35'] """Purple foreground""" +## Cyan foreground +# \ingroup termcolor CYAN_FG = ['36'] """Cyan foreground""" +## White foreground +# \ingroup termcolor WHITE_FG = ['37'] """White foreground""" +## Black background +# \ingroup termcolor BLACK_BG = ['40'] """Black background""" +## Red background +# \ingroup termcolor RED_BG = ['41'] """Red background""" +## Green background +# \ingroup termcolor GREEN_BG = ['42'] """Green background""" +## Yellow background +# \ingroup termcolor YELLOW_BG = ['43'] """Yellow background""" +## Blue background +# \ingroup termcolor BLUE_BG = ['44'] """Blue background""" +## Purple background +# \ingroup termcolor PURPLE_BG = ['45'] """Purple background""" +## Cyan background +# \ingroup termcolor CYAN_BG = ['46'] """Cyan background""" +## White background +# \ingroup termcolor WHITE_BG = ['47'] """White background""" # Constants for common colored text +## Black text (equivalent to BLACK_FG) +# \ingroup termcolor BLACK = BLACK_FG """Black text (equivalent to BLACK_FG)""" +## Red text (equivalent to BOLD + RED_FG) +# \ingroup termcolor RED = BOLD + RED_FG """Red text (equivalent to BOLD + RED_FG)""" +## Green text (equivalent to BOLD + GREEN_FG) +# \ingroup termcolor GREEN = BOLD + GREEN_FG """Green text (equivalent to BOLD + GREEN_FG)""" +## Yellow text (equivalent to BOLD + YELLOW_FG) +# \ingroup termcolor YELLOW = BOLD + YELLOW_FG """Yellow text (equivalent to BOLD + YELLOW_FG)""" +## Blue text (equivalent to BOLD + BLUE_FG) +# \ingroup termcolor BLUE = BOLD + BLUE_FG """Blue text (equivalent to BOLD + BLUE_FG)""" +## Purple text (equivalent to BOLD + PURPLE_FG) +# \ingroup termcolor PURPLE = BOLD + PURPLE_FG """Purple text (equivalent to BOLD + PURPLE_FG)""" +## Cyan text (equivalent to BOLD + CYAN_FG) +# \ingroup termcolor CYAN = BOLD + CYAN_FG """Cyan text (equivalent to BOLD + CYAN_FG)""" +## White text (equivalent to WHITE_FG) +# \ingroup termcolor WHITE = WHITE_FG """White text (equivalent to WHITE_FG)""" - +## Return True if the stream can display colored text, False otherwise. +# \ingroup termcolor def canDisplayColor(stream): """ Return True if the stream can display colored text, False otherwise. """ return hasattr(stream, "isatty") and stream.isatty() +## Return the control sequence for the color in parameter, i.e. the string +# telling the terminal to display the following text in the given color. +# \ingroup termcolor def getControlSequence(color): """ Return the control sequence for the color in parameter, i.e. the string @@ -123,6 +207,9 @@ def getControlSequence(color): seq += "m" return seq +## Return a string that can be used to display the message in parameter with +# the given color. +# \ingroup termcolor def makeColoredMessage(message, color): """ Return a string that can be used to display the message in parameter with @@ -132,6 +219,8 @@ def makeColoredMessage(message, color): str(message) + getControlSequence(DEFAULT)) +## Test function for termcolor module. +# \ingroup termcolor def TEST_termcolor(): """Test function for termcolor module.""" import sys diff --git a/src/KERNEL_PY/kernel/uiexception.py b/src/KERNEL_PY/kernel/uiexception.py index e9ee4ffc1..2999c32c0 100644 --- a/src/KERNEL_PY/kernel/uiexception.py +++ b/src/KERNEL_PY/kernel/uiexception.py @@ -17,11 +17,23 @@ # # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com # + +## \defgroup uiexception uiexception +# \{ +# \details Exception for user error management +# \} + __author__="gboulant" __date__ ="$31 mars 2010 11:59:33$" from enumerate import Enumerate +## This exception should be used for functionnal error management, at least in the GUI +# part of the application, for example to set user oriented messages at point +# of exception raise. +# \warning The exception should NOT be used to hide defaults in the algorithm, but +# only predicted error in the specified use case. +# \ingroup uiexception class UiException(Exception): TYPES = Enumerate([ @@ -40,6 +52,8 @@ class UiException(Exception): WARN: The exception should NOT be used to hide defaults in the algorithm, but only predicted error in the specified use case. """ + + ## Canonical constructor def __init__(self, message, type=TYPES.USER): """Canonical constructor""" Exception.__init__(self,message) @@ -52,6 +66,7 @@ class UiException(Exception): def getUIMessage(self): return self._UImessage + ## Specify the type of this exception. To be choosen in the TYPES list. def setType(self, type): """Specify the type of this exception. To be choosen in the TYPES list.""" if not self.TYPES.isValid(type): diff --git a/src/KERNEL_PY/kernel/unittester.py b/src/KERNEL_PY/kernel/unittester.py index 25b27cb83..f8152534c 100644 --- a/src/KERNEL_PY/kernel/unittester.py +++ b/src/KERNEL_PY/kernel/unittester.py @@ -17,11 +17,22 @@ # # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com # + +## \defgroup unittester unittester +# \{ +# \details Run very basic unit tests +# \} + __author__="gboulant" __date__ ="$1 avr. 2010 09:45:21$" import sys +## This function should be used for very basic unit tests and only for a +# rapid development. %A better way should be the pyunit framework. +# The function functionName is supposed here to return a boolean value +# indicating if the test is OK (True) or NOT OK (False) +# \ingroup unittester def run(modulePath, functionName): """ This function should be used for very basic unit tests and only for a @@ -41,6 +52,11 @@ def run(modulePath, functionName): else: print "[TEST] %s.%s %s NOT OK" % (moduleName, functionName,"."*tabsize) +## This function is for debug only. It executes the specified function with the +# specified arguments in a try/except bloc so that to display the exception in +# the case where an exception is raised (usefull to debug server side of a CORBA +# process). +# \ingroup unittester def tryfunction(function,*argv): """ This function is for debug only. It executes the specified function with the -- 2.39.2