From c5168af3ecf4aebf3027752810a07ef96f369e36 Mon Sep 17 00:00:00 2001 From: boulant Date: Thu, 29 Jul 2010 09:33:38 +0000 Subject: [PATCH] documentation completude --- doc/docutils/Makefile.am | 2 ++ doc/docutils/docapi.rst | 6 ++-- doc/docutils/index.rst | 3 +- doc/docutils/overview.rst | 54 ++++++++++++++++++++++++++++++++++++ doc/docutils/salomepypkg.rst | 32 +++++++++++---------- 5 files changed, 78 insertions(+), 19 deletions(-) create mode 100644 doc/docutils/overview.rst diff --git a/doc/docutils/Makefile.am b/doc/docutils/Makefile.am index 44819790d..9d615ede6 100644 --- a/doc/docutils/Makefile.am +++ b/doc/docutils/Makefile.am @@ -69,6 +69,8 @@ html: RSTFILES= \ index.rst \ + overview.rst \ + docapi.rst \ salomepypkg.rst EXTRA_DIST+= $(RSTFILES) diff --git a/doc/docutils/docapi.rst b/doc/docutils/docapi.rst index 23e9fe095..56ee65286 100644 --- a/doc/docutils/docapi.rst +++ b/doc/docutils/docapi.rst @@ -1,7 +1,7 @@ -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - Programming interface (API) of the ``salome.kernel`` package -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + Documentation of the programming interface (API) +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% This section describes the python packages and modules of the ``salome.kernel`` python package. The main part is generated from the diff --git a/doc/docutils/index.rst b/doc/docutils/index.rst index 1efc96704..a0b8c3a32 100644 --- a/doc/docutils/index.rst +++ b/doc/docutils/index.rst @@ -8,7 +8,8 @@ Main documentation .. toctree:: :maxdepth: 3 - + + overview.rst docapi.rst diff --git a/doc/docutils/overview.rst b/doc/docutils/overview.rst new file mode 100644 index 000000000..341e9b652 --- /dev/null +++ b/doc/docutils/overview.rst @@ -0,0 +1,54 @@ + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +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 makes you ease with the + manipulation of the SALOME study, its ``SComponent`` and + ``SObject``. +* General purpose functions for logging, threading, and other recurent + stuff in python programming. These function has no dependancy with + SALOME and could be used from any python interpreter + +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 + + import salome + salome.salome_init() + salomeStudyId = salome.myStudyId + + from salome.kernel import studyedit + studyEditor = studyedit.getStudyEditor(salomeStudyId) + + myStudyComponent = studyEditor.findOrCreateComponent( + componentName, + componentLabel, + componentIcon, + engineName) + + myStudyItem = studyEditor.createItem( + myStudyComponent, + itemName, + itemComment, + itemType, + itemIcon) + +The specification of the programming interface of this package is +detailled in the part :doc:`Documentation of the programming interface +(API)` of this documentation. + +.. note:: + The main package ``salome`` contains other sub-packages that are + distributed with the other SALOME modules. For example, the GEOM + module provides the python package ``salome.geom`` and SMESH the + package ``salome.smesh``. diff --git a/doc/docutils/salomepypkg.rst b/doc/docutils/salomepypkg.rst index d0d05f168..2e516e3eb 100644 --- a/doc/docutils/salomepypkg.rst +++ b/doc/docutils/salomepypkg.rst @@ -3,12 +3,12 @@ Complement A: Organizing the SALOME python functions in a packaged structure %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -:Contacts: Guillaume Boulant, Christian Caremoli, Renaud Barate +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. -This notes are the instructions 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 ========== @@ -53,8 +53,7 @@ provides SALOME helper functions classified by modules * ``salome.kernel``: helper functions for manipulating the SALOME study and its components (SComponents and SObject). This provides - also general purpose utilities as a simple logging, a threading - helper. + 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 @@ -63,6 +62,8 @@ provides SALOME helper functions classified by modules "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 @@ -73,7 +74,7 @@ and all other stuff should be imported and work as before). Problems ======== -To target this situation, we have to face two 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 @@ -157,8 +158,8 @@ done without impact on existing python user scripts. Instructions ============ -Instructions for creating the python package --------------------------------------------- +Instructions for creating the python packages +--------------------------------------------- Considering the elements described above, a procedure that works to get the packaged python structure is: @@ -182,12 +183,13 @@ get the packaged python structure is: * Adapt the ``apply_gen`` utility to take into account the finer folder hierarchy in ``site-packages``. -Note that all python files that were existing in the KERNEL module -are leaft untouched but the file ``salome.py``. +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``. -By convention, the source code of the python packages of a SALOME -module is located in the source directory -``src/_PY`` (convention already used in the KERNEL). +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 --------------------------------------------- -- 2.39.2