From: Serge Rehbinder <serge.rehbinder@cea.fr>
Date: Fri, 12 Feb 2016 14:42:28 +0000 (+0100)
Subject: Add developer documentation to describe how to add a command to sat
X-Git-Tag: sprint-02
X-Git-Url: http://git.salome-platform.org/gitweb/?a=commitdiff_plain;h=9a4131c40f4705c3df8fc53670275f30b1f60636;p=tools%2Fsat.git

Add developer documentation to describe how to add a command to sat
---

diff --git a/doc/src/index.rst b/doc/src/index.rst
index f2a635a..bf1054a 100644
--- a/doc/src/index.rst
+++ b/doc/src/index.rst
@@ -37,7 +37,13 @@ Code documentation
    
    SAT modules <commands/apidoc/modules.rst>
 
-
+developer documentation
+=======================
+ 
+.. toctree::
+   :maxdepth: 1
+   
+   Add a command <write_command>
 
 Release Notes
 =============
diff --git a/doc/src/write_command.rst b/doc/src/write_command.rst
new file mode 100644
index 0000000..726c553
--- /dev/null
+++ b/doc/src/write_command.rst
@@ -0,0 +1,144 @@
+***************
+Write a command
+***************
+
+Introduction
+============
+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.
+
+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**.
+
+In **mycommand.py**, there must be the following method: ::
+
+    def run(args, runner, logger):
+        # algorithm
+        pass
+
+In fact, at this point, the command will already be functional.
+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 <options>
+    parser = src.options.Options()
+    parser.add_option('m', 'myoption', 'boolean', 'myoption', "My option changes the behavior of my command.")
+
+    def run(args, runner, logger):
+        # Parse the options
+        (options, args) = parser.parse_args(args)
+        # algorithm
+
+
+* 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
+
+    import src
+    
+    # Define all possible option for mycommand command :  sat mycommand <options>
+    parser = src.options.Options()
+    parser.add_option('m', 'myoption', 'boolean', 'myoption', "My option changes the behavior of my command.")
+
+    def description():
+        return _("The help of mycommand.")   
+
+    def run(args, runner, logger):
+        # Parse the options
+        (options, args) = parser.parse_args(args)
+        # algorithm
+
+How to access to salomeTools config and other commands ?
+========================================================
+
+The runner variable is an instance of the Sat class. It gives access to cfg : the data model that is read from all configuration files of salomeTools (*.pyconf) For example, runner.cfg.APPLICATION.out_dir will contain the root directory of the application on which you are working.
+
+It gives also access to all other commands of salomeTools :
+
+.. code-block:: python
+
+    runner.prepare(runner.cfg.VARS.application)
+
+How to log ?
+============
+
+The logger variable is an instance of the Logger class. It gives access to the write method.
+
+When this method is called, the message passed as parameter will be displayed in the termnial and written in an xml log file.
+
+.. code-block:: python
+
+    logger.write("My message", 3)
+
+The second argument defines the level of verbosity that is wanted for this message. It has to be between 1 and 5 (the most verbose level).
+
+HELLO WORLD !
+=============
+
+Here is a hello world command :
+
+.. code-block:: python
+
+    import src
+
+    # Define all possible option for mycommand command :  sat mycommand <options>
+    parser = src.options.Options()
+    parser.add_option('m', 'myoption', 'boolean', 'myoption', "My option changes the behavior of my command.")
+
+    def description():
+        return _("The help of mycommand.")
+    
+    def run(args, runner, logger):
+        # Parse the options
+        (options, args) = parser.parse_args(args)
+        # algorithm
+        if options.myoption:
+            logger.write('HELLO, WORLD !\n')
+        else:
+            logger.write('WORLD, HELLO !\n')
+            
+A first call of mycommand:
+
+.. code-block:: bash
+
+    >./sat mycommand --myoption
+    HELLO, WORLD !
+
+    Tap the following command to get the log :
+    /path/to/salomeTools/sat log
+    
+Another call of mycommand:
+
+.. code-block:: bash
+
+    >./sat mycommand
+    WORLD, HELLO !
+
+    Tap the following command to get the log :
+    /path/to/salomeTools/sat log
+    
+Get the help of mycommand:
+
+.. code-block:: bash
+
+    >./sat --help mycommand
+    Version: 5.0.0dev
+
+    Description:
+    The help of mycommand.
+
+    Available options are:
+     -m, --myoption (boolean)
+             My option changes the behavior of my command.
\ No newline at end of file
diff --git a/src/xmlManager.py b/src/xmlManager.py
index 609f43d..9c84cc1 100644
--- a/src/xmlManager.py
+++ b/src/xmlManager.py
@@ -95,7 +95,9 @@ class readXmlFile(object):
         self.xmlroot = etree_inst.parse(filePath)
     
     def get_attrib(self, node_name):
-        '''Parse the root nodes and get all node that have the attribname. Return the list of [(value of attribname, text), ...]
+        '''Get the attibutes of the node node_name in self.xmlroot
+        
+        :param node_name str: the name of the node
         '''
         return self.xmlroot.find(node_name).attrib