Progresses in docstringing the configurators

Removed unused IConfigurator.add_dependency method
Bad import in PlotterPlugin

Doc/build_doc.sh

 #!/bin/sh
 
-rm -rf Documentation
+MDANSE_API="../MDANSE/Doc/API"
 
-mkdir Documentation
-mkdir Documentation/_static
+#rm -rf ${MDANSE_API}
 
-sphinx-apidoc -o  ./Documentation -F --separate -d 5 -H MDANSE -A "B. Aoun & G. Goret & E. Pellegrini"  -V 1.0 -R 1.0 ../MDANSE/
+#mkdir -p ${MDANSE_API}
+#mkdir ${MDANSE_API}/_static
+#mkdir ${MDANSE_API}/_templates
 
-cp conf_html.py ./Documentation/conf.py
-
-cp mdanse_logo.png ./Documentation/_static/
-
-sphinx-build -b html ./Documentation ./Documentation/_build/html/
+sphinx-apidoc -o  ${MDANSE_API} -F --separate -d 5 -H MDANSE -A "G. Goret & E. Pellegrini"  -V 1.0 -R 1.0 ../MDANSE
 
+cp conf_html.py ${MDANSE_API}/conf.py
 
+cp layout.html ${MDANSE_API}/_templates/
 
+cp mdanse_logo.png ${MDANSE_API}/_static/
 
+sphinx-build -b html ${MDANSE_API} ${MDANSE_API}
 
 

Doc/build_help.sh

@@ -8,7 +8,7 @@ mkdir -p ${MDANSE_HELP}
 mkdir ${MDANSE_HELP}/_static
 mkdir ${MDANSE_HELP}/_templates
 
-sphinx-apidoc -o  ${MDANSE_HELP} -F --separate -d 5 -H MDANSE -A "G. Goret, B. Aoun  & E. Pellegrini"  -V 1.0 -R 1.0 ../MDANSE
+sphinx-apidoc -o  ${MDANSE_HELP} -F --separate -d 5 -H MDANSE -A "G. Goret & E. Pellegrini"  -V 1.0 -R 1.0 ../MDANSE
 
 cp conf_help.py ${MDANSE_HELP}/conf.py
 

Doc/conf_html.py

@@ -90,6 +90,8 @@ pygments_style = 'sphinx'
 
 # -- Options for HTML output ---------------------------------------------------
 
+html_sidebars = {'**': ['localtoc.html','sourcelink.html', 'searchbox.html']}
+
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 html_theme = "nature"

MDANSE/App/GUI/Framework/Plugins/AtomSelectionPlugin.py

@@ -484,6 +484,4 @@ class AtomSelectionPlugin(ComponentPlugin):
 
         self._expression, self._selection = self._query.parse()
         
-        self._parent.show_selected_atoms(self._selection)
-    
-print REGISTRY['plugin']
+        self._parent.show_selected_atoms(self._selection)
\ No newline at end of file

MDANSE/App/GUI/Framework/Plugins/DensitySuperpositionPlugin.py

@@ -200,7 +200,6 @@ class DensitySuperpositionPlugin(ComponentPlugin):
             self.surface.AddPosition(self.xyz[0]*s[0]/2., self.xyz[1]*s[1]/2., self.xyz[2]*s[2]/2.)
         elif key in ['-']:
             self.surface.AddPosition(-self.xyz[0]*s[0]/2., -self.xyz[1]*s[1]/2., -self.xyz[2]*s[2]/2.)
-        print 'current surf position : ', self.surface.GetPosition()
         self.iren.Render()
 
     def on_browse(self, event):

MDANSE/App/GUI/Framework/Plugins/Plotter/Plotter.py → MDANSE/App/GUI/Framework/Plugins/Plotter/PlotterPlugin.py

@@ -41,11 +41,11 @@ import wx.aui as wxaui
 from Scientific.IO.NetCDF import NetCDFFile
 
 from MDANSE.Core.Error import Error
-from MDANSE.App.GUI.Framework.Plugins import ComponentPlugin
-from MDANSE.App.GUI.Icons import ICONS
+from MDANSE.App.GUI.Framework.Plugins.ComponentPlugin import ComponentPlugin
 from MDANSE.App.GUI.Framework.Plugins.Plotter.Plotter1D import Plotter1D
 from MDANSE.App.GUI.Framework.Plugins.Plotter.Plotter2D import Plotter2D
 from MDANSE.App.GUI.Framework.Plugins.Plotter.Plotter3D import Plotter3D
+from MDANSE.App.GUI.Icons import ICONS
 
 class PlotterError(Error):
     pass
@@ -371,7 +371,7 @@ class PlotterPlugin(ComponentPlugin):
         if mode == 'standalone':
             self.make_standalone()
         
-        ComponentPlugin.__init__(self, parent)
+        ComponentPlugin.__init__(self,parent)
         
     def build_panel(self):
         self._dataPanel = DataPanel(self)
@@ -384,12 +384,12 @@ class PlotterPlugin(ComponentPlugin):
         self.standalone = True
         self._dataDict = collections.OrderedDict()
         
-    def plug(self, *args, **kwargs):
+    def plug(self):
         self._data = self.dataproxy.data
         self._dataPanel.show_data()
 
         self._parent._mgr.GetPane(self).Dock().Floatable(False).Center().CloseButton(True).Caption("2D/3D Plotter")
-        self._parent._mgr.Update()        
+        self._parent._mgr.Update()
 
 class PlotterFrame(wx.Frame):
     
@@ -406,8 +406,9 @@ class PlotterFrame(wx.Frame):
         _quit = fileMenu.Append(wx.ID_ANY, 'Quit')
 
         mainMenu.Append(fileMenu, 'File')
-        
-        icon = wx.Icon(ICONS["plot"], wx.BITMAP_TYPE_PNG)
+
+        icon = wx.EmptyIcon()
+        icon.CopyFromBitmap(ICONS["plot",32,32])        
         self.SetIcon(icon) 
         
         self.SetMenuBar(mainMenu)
@@ -471,7 +472,7 @@ class PlotterFrame(wx.Frame):
         
         mainSizer = wx.BoxSizer(wx.VERTICAL)
         
-        self.plugin = PlotterPlugin(mainPanel, mode = 'standalone')
+        self.plugin = PlotterPlugin(mainPanel, 'standalone')
          
         mainSizer.Add(self.plugin, 1, wx.ALL|wx.EXPAND, 5)
 

MDANSE/Core/Platform.py

@@ -43,7 +43,7 @@ from MDANSE.Core.Error import Error
 
 class PlatformError(Error):
     '''
-    Handles error related to Platform derived classes.
+    This class handles error related to Platform derived classes.
     '''
     pass
 

MDANSE/Framework/Configurators/AtomSelectionConfigurator.py

@@ -53,10 +53,11 @@ class AtomSelectionConfigurator(IConfigurator):
 
     Without any selection, all the atoms stored into the trajectory file will be selected.
     
-    To Build an atom selection from the GUI you have to :
-    #. Create a workspace based on a MMTK trajectory data
-    #. Drag a molecular viewer on it
-    #. Drag into the Molecular Viewer the Atom selection plugin
+    To Build an atom selection from the GUI you have to:
+    
+    * Create a workspace based on a MMTK trajectory data
+    * Drag a molecular viewer on it
+    * Drag into the Molecular Viewer the Atom selection plugin
     
     :note: this configurator depends on 'trajectory' and 'grouping_level' configurators to be configured
     '''

MDANSE/Framework/Configurators/AtomTransmutationConfigurator.py

@@ -47,9 +47,10 @@ class AtomTransmutationConfigurator(IConfigurator):
     of the molecular system.
         
     To Build an atomic transmutation from the GUI you have to :
-    #. Create a workspace based on a MMTK trajectory data,
-    #. Drag a molecular viewer on it,
-    #. Drag into the Molecular Viewer the Atom transmutation plugin
+    
+    * Create a workspace based on a MMTK trajectory data,
+    * Drag a molecular viewer on it,
+    * Drag into the Molecular Viewer the Atom transmutation plugin
     
     :note: this configurator depends on 'trajectory' and 'atom_selection' configurators to be properly configured
     """
@@ -60,14 +61,15 @@ class AtomTransmutationConfigurator(IConfigurator):
                                 
     def configure(self, configuration, value):
         '''
-        Configure an given input value. 
+        Configure an input value. 
         
         The value can be:
-        #. None: no transmutation is performed
-        #. (str,str)-dict: for each (str,str) pair, a transmutation will be performed
+        
+        * None: no transmutation is performed
+        * (str,str)-dict: for each (str,str) pair, a transmutation will be performed
         by parsing the 1st element as an atom selection string and transmutating the 
         corresponding atom selection to the target chemical element stored in the 2nd element
-        #. str: the transmutation will be performed by reading the corresponding user definition
+        * str: the transmutation will be performed by reading the corresponding user definition
         
         :param configuration: the current configuration
         :type configuration: a MDANSE.Framework.Configurable.Configurable object

MDANSE/Framework/Configurators/AxisSelectionConfigurator.py

@@ -41,9 +41,10 @@ class AxisSelection(IConfigurator):
     For each molecule, the axis is defined using the coordinates of two atoms of the molecule. 
     
     To Build an axis selection from the GUI you have to :
-    #. Create a workspace based on a mmtk_trajectory data,
-    #. Drag a molecular viewer on it,
-    #. Drag into the Molecular Viewer the Axis selection plugin
+    
+    * Create a workspace based on a mmtk_trajectory data,
+    * Drag a molecular viewer on it,
+    * Drag into the Molecular Viewer the Axis selection plugin
 
     :note: this configurator depends on 'trajectory' configurator to be configured
     """
@@ -57,11 +58,12 @@ class AxisSelection(IConfigurator):
         Configure an input value. 
         
         The value can be:
-        #. a dict with 'molecule', 'endpoint1' and 'endpoint2' keys. 'molecule' key 
+        
+        * a dict with 'molecule', 'endpoint1' and 'endpoint2' keys. 'molecule' key 
         is the molecule name for which the axis selection will be performed
         and 'endpoint1' and 'endpoint2' keys are the names of two atoms of the molecule 
         along which the axis will be defined  
-        #. str: the axis selection will be performed by reading the corresponding user definition
+        * str: the axis selection will be performed by reading the corresponding user definition
         
         :param configuration: the current configuration
         :type configuration: a MDANSE.Framework.Configurable.Configurable object

MDANSE/Framework/Configurators/BasisSelectionConfigurator.py

@@ -43,9 +43,10 @@ class BasisSelection(IConfigurator):
     Z axis being latter defined in such a way that the basis is direct. 
     
     To Build a basis selection from the GUI you have to :
-    #. Create a workspace based on a mmtk_trajectory data,
-    #. Drag a molecular viewer on it,
-    #. Drag into the Molecular Viewer the Basis selection plugin
+    
+    * Create a workspace based on a mmtk_trajectory data,
+    * Drag a molecular viewer on it,
+    * Drag into the Molecular Viewer the Basis selection plugin
     """
     
     type = 'basis_selection'
@@ -57,11 +58,12 @@ class BasisSelection(IConfigurator):
         Configure an input value. 
         
         The value can be:
-        #. a dict with 'molecule', 'origin', 'x_axis' and 'y_axis' keys. 
+        
+        * a dict with 'molecule', 'origin', 'x_axis' and 'y_axis' keys. 
         'molecule' key is the molecule name for which the axis selection will be performed
         and 'origin', 'x_axis' and 'y_axis' keys are the names of three atoms of the molecule 
         that will be used to define respectively the origin, the X and Y axis of the basis  
-        #. str: the axis selection will be performed by reading the corresponding user definition
+        * str: the axis selection will be performed by reading the corresponding user definition
         
         :param configuration: the current configuration
         :type configuration: a MDANSE.Framework.Configurable.Configurable object

MDANSE/Framework/Configurators/FloatConfigurator.py

@@ -64,7 +64,7 @@ class FloatConfigurator(IConfigurator):
         
         self._choices = choices if choices is not None else []
 
-    def configure(self, configuration, value):
+    def configure(self, value):
         '''
         Configure an input value.
                 
@@ -77,7 +77,7 @@ class FloatConfigurator(IConfigurator):
         try:
             value = float(value)
         except (TypeError,ValueError) as e:
-            raise ConfiguratorError(e)
+            raise ConfiguratorError(e,self)
             
         if self._choices:
             if not value in self._choices:

MDANSE/Framework/Configurators/FramesConfigurator.py

@@ -36,11 +36,12 @@ class FramesConfigurator(RangeConfigurator):
     """
     This configurator allows to input a frame selection for the analysis.
     
-    The frame selection can be  be input as:
-    #. a 3-tuple where the 1st, 2nd will corresponds respectively to the indexes of the first and last (excluded) frames to be selected while the 3rd element
+    The frame selection can be input as:
+    
+    * a 3-tuple where the 1st, 2nd will corresponds respectively to the indexes of the first and last (excluded) frames to be selected while the 3rd element
     will correspond to the step number between two frames. For example (1,11,3) will give 1,4,7,10
-    #. 'all' keyword, in such case, all the frames of the trajectory are selected
-    #. None keyword, in such case, all the frames of the trajectory are selected
+    * 'all' keyword, in such case, all the frames of the trajectory are selected
+    * None keyword, in such case, all the frames of the trajectory are selected
 
     :note: this configurator depends on 'trajectory' configurator to be configured
     """

MDANSE/Framework/Configurators/GroupingLevelConfigurator.py

@@ -32,7 +32,6 @@ Created on Mar 30, 2015
 
 import collections
 
-from MDANSE.Framework.Configurators.IConfigurator import ConfiguratorError
 from MDANSE.Framework.Configurators.SingleChoiceConfigurator import SingleChoiceConfigurator
 
 LEVELS = collections.OrderedDict()
@@ -46,18 +45,16 @@ class GroupingLevelConfigurator(SingleChoiceConfigurator):
     """
     This configurator allows to choose the level of granularity in the atom selection.
     
-    The level of granularity will be applied, when reading the trajectory, by grouping the atoms of the selection according to 
-    their level of granularity to a single dummy-atoms located on the center of gravity of those atoms.
+    When reading the trajectory, the level of granularity will be applied by grouping the atoms of the selection
+    to a single dummy-atoms located on the center of gravity of those atoms.
     
     The level of granularity currently supported are:
-    #. 'atom': no grouping will be performed
-    #. 'group': the atoms that belongs to a MMTK AtomCluster object will be grouped as a single atom per object while the ones that belongs to a MMTK Molecule, 
-    NucleotideChain, PeptideChain and Protein object will be grouped according to the chemical group they belong to (e.g. peptide group, methyl group ...).
-    #. 'residue': the atoms that belongs to a MMTK AtomCluster or Molecule object will be grouped as a single atom per object while the ones thta belongs to a
-    MMTK NucleotideChain, PeptideChain or Protein object will be grouped according to the residue to which they belong to (e.g. Histidine, Cytosyl ...)
-    #. 'chain': the atoms that belongs to a MMTK AtomCluster or Molecule object will be grouped as a single atom per object while the ones that belongs to a
-    MMTK NucleotideChain, PeptideChain or Protein object will be grouped according to the chain they belong to
-    #. 'molecule': the atoms that belongs to any MMTK chemical object will be grouped as a single atom per object
+    
+    * 'atom': no grouping will be performed
+    * 'group': the atoms that belongs to a MMTK AtomCluster object will be grouped as a single atom per object while the ones that belongs to a MMTK Molecule, NucleotideChain, PeptideChain and Protein object will be grouped according to the chemical group they belong to (e.g. peptide group, methyl group ...)
+    * 'residue': the atoms that belongs to a MMTK AtomCluster or Molecule object will be grouped as a single atom per object while the ones thta belongs to a MMTK NucleotideChain, PeptideChain or Protein object will be grouped according to the residue to which they belong to (e.g. Histidine, Cytosyl ...)
+    * 'chain': the atoms that belongs to a MMTK AtomCluster or Molecule object will be grouped as a single atom per object while the ones that belongs to a MMTK NucleotideChain, PeptideChain or Protein object will be grouped according to the chain they belong to
+    * 'molecule': the atoms that belongs to any MMTK chemical object will be grouped as a single atom per object
     """
     
     type = 'grouping_level'

MDANSE/Framework/Configurators/IConfigurator.py

@@ -27,7 +27,7 @@
 ''' 
 Created on Mar 30, 2015
 
-@author: pellegrini
+@author: Eric C. Pellegrini
 '''
 
 import abc
@@ -36,13 +36,30 @@ from MDANSE import REGISTRY
 from MDANSE.Core.Error import Error
 
 class ConfiguratorError(Error):
+    '''
+    This class handles any exception related to Configurator-derived object
+    '''
     
     def __init__(self, message, configurator=None):
+        '''
+        Initializes the the object.
+        
+        :param message: the exception message
+        :type message: str
+        :param configurator: the configurator in which the exception was raised
+        :type configurator: an instance or derived instance of a MDANSE.Framework.Configurators.Configurator object
+        '''
 
         self._message = message
         self._configurator = configurator
                 
     def __str__(self):
+        '''
+        Returns the informal string representation of this object.
+        
+        :return: the informal string representation of this object
+        :rtype: str
+        '''
         
         if self._configurator is not None:
             self._message = "Configurator: %r --> %s" % (self._configurator.name,self._message)
@@ -51,9 +68,26 @@ class ConfiguratorError(Error):
     
     @property
     def configurator(self):
+        '''
+        Returns the configurator in which the exception was raised
+
+        :return: the configurator in which the exception was raised
+        :rtype: an instance or derived instance of a MDANSE.Framework.Configurators.Configurator object
+        '''
         return self._configurator
                                                 
 class IConfigurator(dict):
+    '''
+    This class implements the base class for configurator objects. A configurator object is a dictionary-derived object that is used 
+    to configure one input value of a given configuration. Once the input value is configured, the dictionary is updated with keys/values 
+    that depend on the type of configurator type in use.
+    
+    A configurator is not designed to be used as a stand-alone object. It should be used within the scope of a Configurable object that 
+    will store a complete configuration for a given task (e.g. job, Q vectors, instrument resolution ...).
+    
+    Usually, configurator objects are self-consistent but for complex ones, it can happen that they depends on other configurators of the 
+    configuration.
+    '''
     
     __metaclass__ = REGISTRY
 
@@ -64,9 +98,25 @@ class IConfigurator(dict):
     _doc_ = "undocumented"
                             
     def __init__(self, name, dependencies=None, default=None, label=None, widget=None):
+        '''
+        Initializes a configurator object.
+        
+        :param name: the name of this configurator.
+        :type name: str
+        :param dependencies: the other configurators on which this configurator depends on to be configured. This has to be input as a 
+        dictionary that maps the name under which the dependency will be used within the configurator implementation to the actual name 
+        of the configurator on which this configurator is depending on.  
+        :type dependencies: (str,str)-dict
+        :param default: the default value of this configurator.
+        :type default: any python object
+        :param label: the label of the panel in which this configurator will be inserted in the MDANSE GUI.
+        :type label: str
+        :param widget: the configurator widget that corresponds to this configurator.
+        :type widget: str
+        '''
 
         self._name = name
-        
+                
         self._dependencies = dependencies if dependencies is not None else {}
 
         self._default = default if default is not None else self.__class__._default
@@ -77,39 +127,83 @@ class IConfigurator(dict):
             
     @property
     def default(self):
+        '''
+        Returns the default value of this configurator.
+        
+        :return: the default value of this configurator.
+        :rtype: any Python object
+        '''
         
         return self._default
     
     @property
     def dependencies(self):
+        '''
+        Returns the dependencies maps of this configurator.
+        
+        :return: the dependencies maps of this configurator.
+        :rtype: (str,str)-dict
+        '''
         
         return self._dependencies
         
     @property
     def label(self):
+        '''
+        Returns the label of this configurator that will be used when inserting its corresponding widget in a configuration panel.
+        
+        :return: the label of this configurator.
+        :rtype: str 
+        '''
         
         return self._label
 
     @property
     def name(self):
+        '''
+        Returns the name of this configurator. That name will be used as a key of a Configurable object.
+        
+        :return: the name of this configurator.
+        :rtype: str
+        '''
         
         return self._name
 
     @property
     def widget(self):
+        '''
+        Returns the name of the widget that will be associated to this configurator.
+        
+        :return: the name of the configurator-widget.
+        :rtype: str
+        '''
         
         return self._widget
     
     @abc.abstractmethod
     def configure(self, configuration, value):
-        pass
-                        
-    def add_dependency(self, name, conf):
+        '''
+        Configures this configurator with a given value.
         
-        if self._dependencies.has_key(name):
-            raise ConfiguratorError("duplicate dependendy for configurator %s" % name, self)
-                        
+        :param configuration: the current configuration. The configuration is passed at configuration time because it can be used in the case where
+        the configurator depends on other configurators to be comfigured.
+        :type configuration: Framework.Configurable.Configurable object
+        :param value: the input value to be configured.
+        :type value: depends on the configurator
+
+        :note: this is an abstract method.
+        '''
+                                                
     def check_dependencies(self, configured):
+        '''
+        Check that the configurators on which this configurator depends on have already been configured.
+        
+        :param configured: the names of the configurators that have already been configured when configuring this configurator.
+        :type: list of str
+        
+        :return: True if the configurators on which this configurator depends on have already been configured. False otherwise.
+        :rtype: bool
+        '''
         
         for c in self._dependencies.values():
             if c not in configured:
@@ -119,4 +213,13 @@ class IConfigurator(dict):
     
     @abc.abstractmethod
     def get_information(self):
+        '''
+        Returns some informations about this configurator.
+        
+        :return: the information about this configurator
+        :rtype: str
+        
+        :note: this is an abstract method.
+        '''
+
         pass
\ No newline at end of file