From 319a4d02755011fdb7fdd879d771e4246e058044 Mon Sep 17 00:00:00 2001 From: Christian Van Wambeke Date: Tue, 24 Apr 2018 11:31:36 +0200 Subject: [PATCH] set src/custom.css for alabaster Notes: etc --- .../alabaster/alabaster/static/custom.css | 11 -- doc/src/commands/application.rst | 24 ++-- doc/src/commands/clean.rst | 6 +- doc/src/commands/compile.rst | 18 +-- doc/src/commands/config.rst | 25 ++-- doc/src/commands/environ.rst | 121 +++++++++++------- doc/src/commands/generate.rst | 8 +- doc/src/commands/launcher.rst | 12 +- doc/src/commands/log.rst | 17 ++- doc/src/commands/package.rst | 6 +- doc/src/commands/prepare.rst | 39 ++++-- doc/src/conf.py | 16 ++- doc/src/custom.css | 25 ++++ doc/src/index.rst | 2 +- doc/src/write_command.rst | 45 ++++--- 15 files changed, 229 insertions(+), 146 deletions(-) create mode 100644 doc/src/custom.css diff --git a/doc/_themes/alabaster/alabaster/static/custom.css b/doc/_themes/alabaster/alabaster/static/custom.css index 9c6b7cc..3ddd34d 100644 --- a/doc/_themes/alabaster/alabaster/static/custom.css +++ b/doc/_themes/alabaster/alabaster/static/custom.css @@ -1,13 +1,2 @@ /* This file intentionally left blank. */ -/* -http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html -set backquotes: ``text`` for code samples more color red -*/ - -tt, code { - background-color: #ecf0f3; - color: #842; - /* padding: 1px 2px; */ -} - diff --git a/doc/src/commands/application.rst b/doc/src/commands/application.rst index e376109..2052da0 100644 --- a/doc/src/commands/application.rst +++ b/doc/src/commands/application.rst @@ -1,10 +1,12 @@ +.. include:: ../../rst_prolog.rst + Command application ********************* Description =========== -The **application** command creates a virtual SALOME application. +The **application** command creates a virtual SALOME_ application. Virtual SALOME applications are used to start SALOME when distribution is needed. Usage @@ -13,27 +15,27 @@ Usage sat application - Create the virtual application directory in the salomeTool application directory, i.e. ``$APPLICATION.workdir`` + Create the virtual application directory in the salomeTool application directory ``$APPLICATION.workdir``. * Give a name to the application: :: - sat application --name MYAPP + sat application --name - *Remark*: this option overrides the name given in the virtual_app section of the configuration file (``$APPLICATION.virtual_app.name``). + *Remark*: this option overrides the name given in the virtual_app section of the configuration file ``$APPLICATION.virtual_app.name``. * Change the directory where the application is created: :: - sat application --target + sat application --target -* Set a specific SALOME resources catalog (it will be used for the distribution of components on distant machines): :: +* Set a specific SALOME_ resources catalog (it will be used for the distribution of components on distant machines): :: - sat application --catalog + sat application --catalog Note that the catalog specified will be copied to the application directory. * Generate the catalog for a list of machines: :: - sat application --gencat machine,machine2,machine3 + sat application --gencat machine1,machine2,machine3 This will create a catalog by querying each machine through ssh protocol (memory, number of processor) with ssh. @@ -48,8 +50,6 @@ The virtual application can be configured with the virtual_app section of the co * **APPLICATION.virtual_app** - * **name**: name of the launcher (to replace the default runAppli). - * **application_name**: (optional) the name of the virtual application directory. - - * if missing the default value is '$name + _appli'. + * **name** : name of the launcher (to replace the default runAppli). + * **application_name** : (optional) the name of the virtual application directory, if missing the default value is ``$name + _appli``. diff --git a/doc/src/commands/clean.rst b/doc/src/commands/clean.rst index 47935e6..8ec9b9f 100644 --- a/doc/src/commands/clean.rst +++ b/doc/src/commands/clean.rst @@ -7,7 +7,7 @@ Command clean Description ============ -The **clean** command removes products in the SOURCES, BUILD, or INSTALL directories of an application. +The **clean** command removes products in the *source, build, or install* directories of an application. Theses directories are usually named ``SOURCES, BUILD, INSTALL``. Use the options to define what directories you want to suppress and to set the list of products @@ -46,8 +46,8 @@ Availables options * **--sources_without_dev**: - | Do not clean the products in development mode. - | have they VCS_ commits pending? + | Do not clean the products in development mode, + | (they could have VCS_ commits pending). diff --git a/doc/src/commands/compile.rst b/doc/src/commands/compile.rst index c7cd044..915705e 100644 --- a/doc/src/commands/compile.rst +++ b/doc/src/commands/compile.rst @@ -1,10 +1,12 @@ +.. include:: ../../rst_prolog.rst + Command compile **************** Description =========== -The **compile** command allows compiling the products of a SALOME application. +The **compile** command allows compiling the products of a SALOME_ application. Usage @@ -17,7 +19,7 @@ Usage sat compile --products , ... -* Use **sat -t** to duplicate the logs in the terminal (by default the log are stored and displayed with *sat log* command): :: +* Use *sat -t* to duplicate the logs in the terminal (by default the log are stored and displayed with *sat log* command): :: sat -t compile --products @@ -33,7 +35,7 @@ Usage sat compile --products GEOM --clean_all - .. note:: | a warning will be shown if option --products is missing + .. note:: | a warning will be shown if option *--products* is missing | (as it will clean everything) * Clean only the install directories before starting compilation: :: @@ -44,19 +46,19 @@ Usage sat compile --products --make_flags -* Use the --check option to execute the unit tests after compilation: :: +* Use the *--check* option to execute the unit tests after compilation: :: sat compile --check -* Remove the build directory after successful compilation (some build directory like qt are big!): :: +* Remove the build directory after successful compilation (some build directory like qt are big): :: sat compile --products qt --clean_build_after -* Stop the compilation as soon as a the compilation of a module fails: :: +* Stop the compilation as soon as the compilation of a module fails: :: sat compile --stop_first_fail -* Do not compile! just show if products are installed or not, and where is the installation: :: +* Do not compile, just show if products are installed or not, and where is the installation: :: sat compile --show @@ -64,7 +66,7 @@ Usage Some useful configuration pathes ================================= -The way to compile a product is defined in the product configuration file (pyconf). +The way to compile a product is defined in the *pyconf file configuration*. The main options are: * **build_source** : the method used to build the product (cmake/autotools/script) diff --git a/doc/src/commands/config.rst b/doc/src/commands/config.rst index 3e1a743..79a4a46 100644 --- a/doc/src/commands/config.rst +++ b/doc/src/commands/config.rst @@ -1,4 +1,6 @@ +.. include:: ../../rst_prolog.rst + Command config ****************** @@ -9,11 +11,11 @@ It allows display, manipulation and operation on configuration files Usage ===== -* Edit the user personal configuration file (~/.salomeTools/SAT.pyconf). It is used to store the user personal choices, like the favorite editor, browser, pdf viewer: :: +* Edit the user personal configuration file ``$HOME/.salomeTools/SAT.pyconf``. It is used to store the user personal choices, like the favorite editor, browser, pdf viewer: :: sat config --edit -* List the available applications (they come from the sat projects defined in data/local.pyconf): :: +* List the available applications (they come from the sat projects defined in ``data/local.pyconf``: :: sat config --list @@ -30,7 +32,7 @@ Usage | Use *--no_label* option to get *only* the value, *without* label (useful in automatic scripts). | Examples (with *SALOME-xx* as *SALOME-8.4.0* ): - :: + .. code-block:: bash # sat config --value sat config --value . # all the configuration @@ -50,8 +52,9 @@ Usage sat config SALOME-xx -g USER - .. note:: And so, not only for fun, to get **all expressions** of configuration - :: + .. note:: And so, *not only for fun*, to get **all expressions** of configuration + + .. code-block:: bash sat config SALOME-xx -g . | grep -e "-->" @@ -60,20 +63,22 @@ Usage sat config SALOME-xx --show_patchs -* Get information on a product configuration: :: +* Get information on a product configuration: + + .. code-block:: bash # sat config --info - sat config SALOME-xx--info KERNEL + sat config SALOME-xx --info KERNEL sat config SALOME-xx --info qt Some useful configuration pathes ================================= -To know for exploring a current configuration. +Exploring a current configuration. -* PATHS: To get list of directories where to find files. +* **PATHS**: To get list of directories where to find files. -* USER: To get user preferences (editor, pdf viewer, web browser, default working dir). +* **USER**: To get user preferences (editor, pdf viewer, web browser, default working dir). sat commands: :: diff --git a/doc/src/commands/environ.rst b/doc/src/commands/environ.rst index cb8b53f..13b9508 100644 --- a/doc/src/commands/environ.rst +++ b/doc/src/commands/environ.rst @@ -1,92 +1,121 @@ +.. include:: ../../rst_prolog.rst + Command environ **************** Description =========== -The **environ** command generates the environment files used to run and compile SALOME. -Please note that these files are not required, -salomeTool set the environment himself, when compiling. -And so does the salome launcher. -These files are useful when someone wants to check the environment. -They could be used in debug mode to set the environment for gdb. +The **environ** command generates the environment files used +to run and compile your application (as SALOME_ is an example). + +.. note :: + these files are **not** required, + salomeTool set the environment himself, when compiling. + And so does the salome launcher. + + These files are useful when someone wants to check the environment. + They could be used in debug mode to set the environment for *gdb*. + The configuration part at the end of this page explains how -to specify the environment which will be used by sat (at build or run time), -and which is written in files by sat environ command. +to specify the environment used by sat (at build or run time), +and saved in some files by *sat environ* command. Usage ===== -* Create the (sh) environment files of the application: :: +* Create the shell environment files of the application: :: sat environ * Create the environment files of the application for a given shell. - Options are bash, bat (for windows) and cfg (the configuration format used by salomé): :: + Options are bash, bat (for windows) and cfg (the configuration format used by SALOME_): :: sat environ --shell [bash|cfg|all] -* Use a different prefix for the files (default is 'env'): :: +* Use a different prefix for the files (default is 'env'): + .. code-block:: bash + + # This will create file _launch.sh, _build.sh sat environ --prefix - This will create file _launch.sh, _build.sh... -* Use a different target directory for the files: :: +* Use a different target directory for the files: + + .. code-block:: bash + # This will create file env_launch.sh, env_build.sh + # in the directory corresponding to sat environ --target - This will create file env_launch.sh, env_build.sh... in the directory corresponding to -* Generate the environment files only with the given products: :: +* Generate the environment files only with the given products: + + .. code-block:: bash - sat environ --product --product .... - This will create the environment files only for the given products and their prerequisites. - It is useful when you want to visualise which environment uses sat to compile a given product. + # This will create the environment files only for the given products + # and their prerequisites. + # It is useful when you want to visualise which environment uses + # sat to compile a given product. + sat environ --product ,, ... Configuration ============= -The specification of the environment can be done through sevaral mechanisms. +The specification of the environment can be done through several mechanisms. -1. For salome products (the products with the property is_SALOME_module : "yes") the environment is set automatically by sat, in respect with Salomé requirements. +1. For salome products (the products with the property ``is_SALOME_module`` as ``yes``) the environment is set automatically by sat, in respect with SALOME_ requirements. 2. For other products, the environment is set with the use of the environ section within the pyconf file of the product. The user has two possibilities, either set directly the environment within the section, or specify a python script which wil be used to set the environment programmatically. Within the section, the user can define environment variables. He can also modify PATH variables, by appending or prepending directories. -In the following example, we prepend /lib to LD_LIBRARY_PATH (note the underscore before), append /lib to PYTHONPATH (the underscore is after!), and set LAPACK_ROOT_DIR to : :: +In the following example, we prepend */lib* to ``LD_LIBRARY_PATH`` (note the *left first* underscore), append */lib* to ``PYTHONPATH`` (note the *right last* underscore), and set ``LAPACK_ROOT_DIR`` to **: + +.. code-block:: python environ : { - _LD_LIBRARY_PATH : $install_dir + $VARS.sep + "lib" - PYTHONPATH_ : $install_dir + $VARS.sep + "lib" - LAPACK_ROOT_DIR : $install_dir + _LD_LIBRARY_PATH : $install_dir + $VARS.sep + "lib" + PYTHONPATH_ : $install_dir + $VARS.sep + "lib" + LAPACK_ROOT_DIR : $install_dir } -It is possible here to distinguish the build environment from the launch environment. For that, use a subsection called build or launch. In the example below, LD_LIBRARY_PATH and PYTHONPATH are only modified at run time, not at compile time: :: +It is possible to distinguish the build environment from the launch environment: use a subsection called *build* or *launch*. In the example below, ``LD_LIBRARY_PATH`` and ``PYTHONPATH`` are only modified at run time, not at compile time: + +.. code-block:: python environ : { - build - { - LAPACK_ROOT_DIR : $install_dir - } - launch - { - LAPACK_ROOT_DIR : $install_dir - _LD_LIBRARY_PATH : $install_dir + $VARS.sep + "lib" - PYTHONPATH_ : $install_dir + $VARS.sep + "lib" - } + build : + { + LAPACK_ROOT_DIR : $install_dir + } + launch : + { + LAPACK_ROOT_DIR : $install_dir + _LD_LIBRARY_PATH : $install_dir + $VARS.sep + "lib" + PYTHONPATH_ : $install_dir + $VARS.sep + "lib" + } } -3. The last possibility is to set the environment with a python script. The script should be provided in the products/env_scripts directory of the sat project, and its name is specified in the environment section with the key **env_script**: :: +3. The last possibility is to set the environment with a python script. The script should be provided in the *products/env_scripts* directory of the sat project, and its name is specified in the environment section with the key ``environ.env_script``: + +.. code-block:: python environ : { - env_script : "lapack.py" + env_script : 'lapack.py' } Please note that the two modes are complementary and are both taken into account. -Most of the time, the first mode is sufficient. The second mode can be used when the environment has to be set programmatically. -Here is an example: :: +Most of the time, the first mode is sufficient. + +The second mode can be used when the environment has to be set programmatically. +The developer implements a handle (as a python method) +which is called by sat to set the environment. +Here is an example: + +.. code-block:: python + #!/usr/bin/env python #-*- coding:utf-8 -*- @@ -99,12 +128,12 @@ Here is an example: :: env.prepend('PATH', os.path.join(prereq_dir, 'bin')) env.prepend('PATH', os.path.join(prereq_dir, 'include')) env.prepend('LD_LIBRARY_PATH', os.path.join(prereq_dir, 'lib')) - pass + return + +SalomeTools defines four handles: -The developer implements a handle which is called by sat to set the environment. -sat defines four handles: +* **set_env(env, prereq_dir, version)** : used at build and run time. +* **set_env_launch(env, prereq_dir, version)** : used only at run time (if defined!) +* **set_env_build(env, prereq_dir, version)** : used only at build time (if defined!) +* **set_native_env(env)** : used only for native products, at build and run time. -* *set_env(env, prereq_dir, version)* : used at build and run time. -* *set_env_launch(env, prereq_dir, version)* : used only at run time (if defined!) -* *set_env_build(env, prereq_dir, version)* : used only at build time (if defined!) -* *set_native_env(env)* : used only for native products, at build and run time. diff --git a/doc/src/commands/generate.rst b/doc/src/commands/generate.rst index 632a29c..f753261 100644 --- a/doc/src/commands/generate.rst +++ b/doc/src/commands/generate.rst @@ -1,4 +1,6 @@ -**************** + +.. include:: ../../rst_prolog.rst + Command generate **************** @@ -27,11 +29,11 @@ Usage * Generate only specific modules: :: - sat generate --products + sat generate --products Remark: modules which don't have the *generate* property are ignored. * Use a specific version of YACSGEN: :: - sat generate --yacsgen + sat generate --yacsgen diff --git a/doc/src/commands/launcher.rst b/doc/src/commands/launcher.rst index 53af1e9..864a31a 100644 --- a/doc/src/commands/launcher.rst +++ b/doc/src/commands/launcher.rst @@ -1,10 +1,12 @@ +.. include:: ../../rst_prolog.rst + Command launcher ****************** Description =========== -The **launcher** command creates a SALOME launcher (a python command to start SALOME). +The **launcher** command creates a SALOME launcher, a python script file to start SALOME_. Usage @@ -15,11 +17,11 @@ Usage Generate a launcher in the application directory, i.e ``$APPLICATION.workdir``. -* Create a launcher with a given name (default name is APPLICATION.profile.launcher_name) :: +* Create a launcher with a given name (default name is ``APPLICATION.profile.launcher_name``) :: sat launcher --name ZeLauncher - The launcher will called ZeLauncher. + The launcher will be called *ZeLauncher*. * Set a specific resources catalog: :: @@ -45,6 +47,6 @@ Some useful configuration pathes: * **APPLICATION.profile** - * **product**: the name of the profile product (the product in charge of holding the application stuff, like logos, splashscreen) - * **launcher_name**: the name of the launcher. + * **product** : the name of the profile product (the product in charge of holding the application stuff, like logos, splashscreen) + * **launcher_name** : the name of the launcher. diff --git a/doc/src/commands/log.rst b/doc/src/commands/log.rst index 8f6e2e7..9908f4b 100644 --- a/doc/src/commands/log.rst +++ b/doc/src/commands/log.rst @@ -1,4 +1,5 @@ +.. include:: ../../rst_prolog.rst Command log **************** @@ -17,27 +18,29 @@ Usage sat log -* The --terminal (or -t) display the log directly in the terminal, through a interactive menu: :: +* The --terminal (or -t) display the log directly in the terminal, through a CLI_ interactive menu: :: - sat log () --terminal + sat log --terminal * The --last option displays only the last command: :: - sat log () --last + sat log --last * To access the last compilation log in terminal mode, use --last_terminal option: :: - sat log () --last_terminal + sat log --last_terminal * The --clean (int) option erases the n older log files and print the number of remaining log files: :: - sat log () --clean 50 + sat log --clean 50 Some useful configuration pathes ================================= -* USER.browser +* **USER** + + * **browser** : The browser used to show the log (by default *firefox*). + * **log_dir** : The directory used to store the log files. - * **browser**: The browser used to show the log (by default *firefox*). diff --git a/doc/src/commands/package.rst b/doc/src/commands/package.rst index 4465f0a..dee6863 100644 --- a/doc/src/commands/package.rst +++ b/doc/src/commands/package.rst @@ -26,7 +26,7 @@ Usage sat package SALOME_xx This command will create an archive named ``SALOME_xx.tgz`` - in the working directory (``$USER.workDir``). + in the working directory (``USER.workDir``). If the archive already exists, do nothing. @@ -35,7 +35,7 @@ Usage sat package SALOME_xx --name YourSpecificName .. note:: - By default, the archive is created in the working directory of the user (``$USER.workDir``). + By default, the archive is created in the working directory of the user (``USER.workDir``). If the option *name* is used with a path (relative or absolute) it will be used. If the option *name* is not used and binaries (prerequisites and products) are included in the package, the OS_ architecture @@ -68,7 +68,7 @@ Usage * Do not delete Version Control System (VCS_) informations from the configurations files of the embedded salomeTools: :: - sat package --with_vcs + sat package SALOME_xx --with_vcs The version control systems known by this option are CVS_, SVN_ and Git_. diff --git a/doc/src/commands/prepare.rst b/doc/src/commands/prepare.rst index 7fc79d5..a28fdae 100644 --- a/doc/src/commands/prepare.rst +++ b/doc/src/commands/prepare.rst @@ -1,13 +1,15 @@ +.. include:: ../../rst_prolog.rst + Command prepare **************** Description =========== -The **prepare** command brings the sources of an application in the SOURCES -application directory, in order to compile them with the compile command. +The **prepare** command brings the sources of an application in the *sources +application directory*, in order to compile them with the compile command. -The sources can be prepared from VCS software (*cvs*,*svn*, *git*), an archive or a directory. +The sources can be prepared from VCS software (*cvs, svn, git*), an archive or a directory. .. warning:: When sat prepares a product, it first removes the existing directory, except if the development mode is activated. @@ -25,7 +27,7 @@ For example, to prepare modules from a cvs server, you first need to login once. To avoid typing a password for each product, you may use a ssh key with passphrase, or store your password -(in .cvspass or .gitconfig). +(in .cvspass or .gitconfig files). If you have security concerns, it is also possible to use a bash agent and type your password only once. @@ -38,12 +40,14 @@ By default *prepare* uses *export* mode: it creates an image of the sources, corresponding to the tag or branch specified, without any link to the VCS base. To perform a *checkout* (svn, cvs) or a *git clone* (git), -you need to declare the product in dev mode in your application configuration. -For that, edit the application configuration and modify the product declaration: :: +you need to declare the product in dev mode in your application configuration: +edit the application configuration file (pyconf) and modify the product declaration: + +.. code-block:: bash sat config -e - # edit the product section : - # : {tag : "my_tag", dev : "yes", debug : "yes"} + # and edit the product section: + # : {tag : "my_tag", dev : "yes", debug : "yes"} The first time you will execute the *sat prepare* command, your module will be downloaded in *checkout* mode @@ -79,11 +83,18 @@ Usage Some useful configuration pathes ================================= -Command *sat prepare* uses the file pyconf configuration of each product to know how to get the sources. +Command *sat prepare* uses the *pyconf file configuration* of each product to know how to get the sources. + +.. note:: to verify configuration of a product, and get name of this *pyconf files configuration* + + .. code-block :: bash + + sat config --info + * **get_method**: the method to use to prepare the module, possible values are cvs, git, archive, dir. -* **git_info**: (used if get_method = git) information to prepare sources from git. -* **svn_info**: (used if get_method = svn) information to prepare sources from cvs. -* **cvs_info**: (used if get_method = cvs) information to prepare sources from cvs. -* **archive_info**: (used if get_method = archive) the path to the archive. -* **dir_info**: (used if get_method = dir) the directory with the sources. +* **git_info** : (used if get_method = git) information to prepare sources from git. +* **svn_info** : (used if get_method = svn) information to prepare sources from cvs. +* **cvs_info** : (used if get_method = cvs) information to prepare sources from cvs. +* **archive_info** : (used if get_method = archive) the path to the archive. +* **dir_info** : (used if get_method = dir) the directory with the sources. diff --git a/doc/src/conf.py b/doc/src/conf.py index e7d0be7..38e7e48 100644 --- a/doc/src/conf.py +++ b/doc/src/conf.py @@ -14,6 +14,17 @@ import sys import os +# Append source folder to path in order to enable autodoc +currentPath = os.path.dirname(__file__) +print "sphinx on file", __file__ +sys.path.append(os.path.join(currentPath, '..', '..')) + +# https://stackoverflow.com/questions/23462494/how-to-add-a-custom-css-file-to-sphinx +def setup(app): + custom = os.path.join(currentPath, 'custom.css') + print "setup add_stylesheet", custom + app.add_stylesheet(custom) + # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. @@ -251,7 +262,4 @@ man_pages = [ [u'CEA DEN/DANS/DM2S/STMF/LGLS'], 1) ] -# Append source folder to path in order to enable autodoc -currentPath = os.path.dirname(__file__) -print "file conf.py currentPath", currentPath -sys.path.append(os.path.join(currentPath, '..', '..')) + diff --git a/doc/src/custom.css b/doc/src/custom.css new file mode 100644 index 0000000..a088ba6 --- /dev/null +++ b/doc/src/custom.css @@ -0,0 +1,25 @@ +/* This file is for theme alabaster custom. */ + +/* +http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html +set backquotes: ``text`` for code samples more color red +*/ +tt, code { + background-color: #ecf0f3; + color: #842; + /* padding: 1px 2px; */ +} + +/* +set 'Note:' etc size less than titles +*/ +div.admonition p.admonition-title { + font-family: {{ theme_head_font_family }}; + font-weight: normal; + font-size: 16px; + margin: 0 0 10px 0; + padding: 0; + line-height: 1; +} + + diff --git a/doc/src/index.rst b/doc/src/index.rst index 69335c4..2cfb090 100644 --- a/doc/src/index.rst +++ b/doc/src/index.rst @@ -9,7 +9,7 @@ Salome Tools :scale: 100 % :align: center -.. note:: This documentation is under construction. +.. warning:: This documentation is under construction. The **Sa**\ lome\ **T**\ ools (sat) is a suite of commands that can be used to perform operations on SALOME_. diff --git a/doc/src/write_command.rst b/doc/src/write_command.rst index 652fbbe..9a68de8 100644 --- a/doc/src/write_command.rst +++ b/doc/src/write_command.rst @@ -1,4 +1,6 @@ +.. include:: ../rst_prolog.rst + Add a user custom command *************************** @@ -6,23 +8,23 @@ Add a user custom command Introduction ============ -.. note:: This documentation is for python developers. +.. note:: This documentation is for Python_ developers. The salomeTools product provides a simple way to develop commands. -The first thing to do is to add a file with ".py" extension in the **commands** directory of salomeTools. +The first thing to do is to add a file with *.py* extension in the ``commands`` directory of salomeTools. Here are the basic requirements that must be followed in this file in order to add a command. Basic requirements ================== -By adding a file **mycommand.py** in the **commands** directory, salomeTools will define a new command named **mycommand**. +By adding a file *mycommand.py* in the ``commands`` directory, salomeTools will define a new command named ``mycommand``. -In **mycommand.py**, there must be the following method: :: +In *mycommand.py*, there must be the following method: :: def run(args, runner, logger): - # algorithm + # your algorithm ... pass In fact, at this point, the command will already be functional. @@ -31,13 +33,14 @@ But there are some useful services provided by salomeTools : * You can give some options to your command: .. code-block:: python - :emphasize-lines: 1,3,4,5,8,9 import src - # Define all possible option for mycommand command : sat mycommand + # Define all possible option for mycommand command : 'sat mycommand ' parser = src.options.Options() - parser.add_option('m', 'myoption', 'boolean', 'myoption', "My option changes the behavior of my command.") + parser.add_option('m', 'myoption', \ + 'boolean', 'myoption', \ + 'My option changes the behavior of my command.') def run(args, runner, logger): # Parse the options @@ -45,17 +48,19 @@ But there are some useful services provided by salomeTools : # algorithm -* You can add a **description** method that will display a message when the user will call the help: +* You can add a *description* method that will display a message when the user will call the help: .. code-block:: python - :emphasize-lines: 7,8 + :emphasize-lines: 9,10 import src - # Define all possible option for mycommand command : sat mycommand + # Define all possible option for mycommand command : 'sat mycommand ' parser = src.options.Options() - parser.add_option('m', 'myoption', 'boolean', 'myoption', "My option changes the behavior of my command.") + parser.add_option('m', 'myoption', \ + 'boolean', 'myoption', \ + 'My option changes the behavior of my command.') def description(): return _("The help of mycommand.") @@ -69,15 +74,16 @@ HowTo access salomeTools config and other commands ======================================================== The *runner* variable is an python instance of *Sat* class. -It gives access to *runner.cfg* : the data model that is read from all -configuration files of salomeTools (*.pyconf) -For example, *runner.cfg.APPLICATION.workdir* will -contain the root directory of the application on which you are working. +It gives access to *runner.cfg* which is the data model defined from all +*configuration pyconf files* of salomeTools +For example, *runner.cfg.APPLICATION.workdir* +contains the root directory of the current application. The *runner* variable gives also access to other commands of salomeTools: .. code-block:: python + # as CLI_ 'sat prepare ...' runner.prepare(runner.cfg.VARS.application) HowTo logger @@ -91,7 +97,7 @@ will be displayed in the terminal and written in an xml log file. .. code-block:: python - logger.write("My message", 3) + logger.write("My message", 3) # 3 as default The second argument defines the level of verbosity that is wanted for this message. @@ -100,7 +106,7 @@ It has to be between 1 and 5 (the most verbose level). HELLO example ============== -Here is a 'hello' command, file *commands/hello.py*: +Here is a *hello* command, file *commands/hello.py*: .. code-block:: python @@ -111,6 +117,7 @@ Here is a 'hello' command, file *commands/hello.py*: Define all possible options for hello command: sat hello """ + parser = src.options.Options() parser.add_option('f', 'french', 'boolean', 'french', "french set hello message in french.") @@ -134,7 +141,7 @@ A first call of hello: ./sat --help hello # To get bonjour - ./sat hello -f + ./sat hello --french Bonjour tout le monde! # To get hello -- 2.39.2