update doc

doc/config.txt

@@ -6,15 +6,17 @@ Options handling basics
 
 Tiramisu is made of almost three main objects :
 
-- :class:`tiramisu.config.Config` which is the whole configuration entry point
 - :class:`tiramisu.option.Option` stands for the option types
 - :class:`tiramisu.option.OptionDescription` is the shema, the option's structure
+- :class:`tiramisu.config.Config` which is the whole configuration entry point
+
+.. image:: config.png
 
 Accessing the `Option`'s
 -------------------------
 
 The :class:`~tiramisu.config.Config` object attribute access notation stands for 
-the value of the configuration's :class:`~tiramisu.option.Option`. That is, the 
+the value of the configuration's :class:`~tiramisu.option.Option`.
 :class:`~tiramisu.config.Config`'s object attribute is the name of the option, 
 and the value is the value accessed by the `__getattr__` attribute access 
 mechanism.
@@ -49,7 +51,7 @@ are organized into a tree into nested
 as does every option group. The parts of the full name of the option are 
 separated by dots: e.g. ``cfg.optgroup.optname``.
 
-Let's make the protocol of accessing a config's attribute explicit
+Let's make the protocol of accessing a `Config`'s attribute explicit
 (because explicit is better than implicit):
 
 1. If the option has not been declared, an `AttributeError` is raised,
@@ -67,11 +69,11 @@ But there are special exceptions. We will see later on that an option can be a
 :term:`mandatory option`. A mandatory option is an option that must have a value 
 defined.
 
-Setting the values of the options
+Setting the value of an option
-----------------------------------------
+------------------------------
 
-An important part of the setting of the configuration consists of setting the
+An important part of the setting's configuration consists of setting the
-values of the configuration options. There are different ways of setting values,
+value's option. There are different ways of setting values,
 the first one is of course the `__setattr__` method
 
 ::
@@ -103,10 +105,10 @@ Let's perform some common manipulation on some options
 
 >>> from tiramisu.config import Config
 >>> from tiramisu.option import UnicodeOption, OptionDescription
->>>
+>>> #
 >>> var1 = UnicodeOption('var1', 'first variable')
 >>> var2 = UnicodeOption('var2', '', u'value')
->>>
+>>> #
 >>> od1 = OptionDescription('od1', 'first OD', [var1, var2])
 >>> rootod = OptionDescription('rootod', '', [od1])
 
@@ -127,10 +129,11 @@ None
 >>> print c.od1.var2
 value
 
-let's modify a value (careful to the value's type...)
+let's modify a value (be careful to the value's type...)
 
 >>> c.od1.var1 = 'value'
-Traceback (most recent call last): ValueError: invalid value value for option var1
+Traceback (most recent call last):
+ValueError: invalid value value for option var1
 >>> c.od1.var1 = u'value'
 >>> print c.od1.var1
 value
@@ -153,7 +156,8 @@ On the other side, in the `read_only` mode, it is not possible to modify the val
 >>> c.read_only()
 >>> c.od1.var2 = u'value2'
 Traceback (most recent call last):
-tiramisu.error.PropertiesOptionError: cannot change the value to var2 for option ['frozen'] this option is frozen
+tiramisu.error.PropertiesOptionError: cannot change the value for option var2 this option is frozen
+
 
 let's retrieve the option `var1` description
 
@@ -184,7 +188,7 @@ That's why a tree of options can easily be searched. First, let's build such a t
 >>> c = Config(rootod)
 >>> c.read_write()
 
-Second, let's find an option by his name::
+Second, let's find an option by it's name::
 
     >>> print c.find(byname='var1')
     [<tiramisu.option.UnicodeOption object at 0x7ff1bf7d6ef0>, 
@@ -232,7 +236,7 @@ If the organisation in a tree is not important,
 {'var5': None, 'var4': None, 'var6': None, 'var1': u'value', 'var3': None, 
 'var2': None}
 
-.. note:: carefull with this `flatten` parameter, here we have just lost 
+.. note:: be carefull with this `flatten` parameter, here we have just lost 
                two options named `var1`
 
 One can export only interesting parts of a tree of options into a dict, for 
@@ -249,7 +253,7 @@ and of course, :meth:`~config.SubConfig.make_dict()` can be called in a subtree:
 >>> print c.od1.make_dict(withoption='var1')
 {'var1': None, 'var3': None, 'var2': None}
 
-the owners
+The owners
 ~~~~~~~~~~~
 
 .. glossary::
@@ -267,24 +271,36 @@ the owners
             
 Then let's retrieve the owner associated to an option::
 
-    >>> print c.getowner('var1')
+   >>> print c.getowner(var1)
-    default
+   default
-    >>> c.od1.var1 = u'non'
+   >>> c.od1.var1 = u'no'
-    >>> print c.getowner('var1')
+   >>> print c.getowner(var1)
-    user
+   user
-    >>> del(c.var1)
+   >>> del(c.var1)
-    >>> print c.getowner('var1')
+   >>> print c.getowner(var1)
-    default
+   default
-    
+
-the properties
+You can create your own owner, for example to distinguish modification made by
-~~~~~~~~~~~~~~~~
+one user to an other one's.
+
+   >>> from tiramisu.setting import owners
+   >>> owners.addowner('toto')
+   >>> c.cfgimpl_get_settings().setowner(owners.toto)
+   >>> print c.getowner(var1)
+   default
+   >>> c.od1.var1 = u'no'
+   >>> print c.getowner(var1)
+   toto
+ 
+The properties
+~~~~~~~~~~~~~~
 
 A property is an information on an option's state. 
 Let's create options with properties::
 
     >>> var1 = UnicodeOption('var1', '', u'value', properties=('hidden',))
     >>> var2 = UnicodeOption('var2', '', properties=('mandatory',))
-    >>> var3 = UnicodeOption('var3', '', u'value', properties=('frozen', 'inconnu'))
+    >>> var3 = UnicodeOption('var3', '', u'value', properties=('frozen', 'unknown'))
     >>> var4 = UnicodeOption('var4', '', u'value')
     >>> od1 = OptionDescription('od1', '', [var1, var2, var3])
     >>> od2 = OptionDescription('od2', '', [var4], properties=('hidden',))
@@ -338,17 +354,17 @@ Let's try to modify a frozen option::
 Tiramisu allows us to use user defined properties. Let's define and use one in 
 read/write or read only mode::
 
-    >>> c.cfgimpl_get_settings().append('inconnu')
+    >>> c.cfgimpl_get_settings().append('unknown')
     >>> print c.od1.var3
     Traceback (most recent call last):
     tiramisu.error.PropertiesOptionError: trying to access to an option named: 
-    var3 with properties ['inconnu']
+    var3 with properties ['unknown']
-    >>> c.cfgimpl_get_settings().remove('inconnu')
+    >>> c.cfgimpl_get_settings().remove('unknown')
     >>> print c.od1.var3
     value 
     
-Properties can also be defined on an option group, (that is, on an 
+Properties can also be defined on an option group (that is, on an 
-:term:`option description`), let's hide a group and try to access to it::
+:term:`option description`) let's hide a group and try to access to it::
 
     >>> c.read_write()
     >>> print c.od2.var4

doc/index.txt

@@ -33,8 +33,8 @@ controlling options explanations
 
     getting-started
     config
-    storage
     option
+    storage
     status
     consistency
     error

doc/option.txt

@@ -9,7 +9,7 @@ Description of Options
 ----------------------
 
 All the constructors take a ``name`` and a ``doc`` argument as first
-arguments to give the option or option group a name and to document it.
+arguments to give to the option or option description a name and a description document.
 Most constructors take a ``default`` argument that specifies the default
 value of the option. If this argument is not supplied the default value
 is assumed to be ``None``.
@@ -17,7 +17,7 @@ is assumed to be ``None``.
 The `Option` base class
 -------------------------
 
-It's the abstract base class for almost all options (except the symblink).
+It's the abstract base class for almost all options (except the symlink).
 
 .. _optioninit:
 
@@ -28,22 +28,41 @@ It's the abstract base class for almost all options (except the symblink).
 All option types
 ------------------
 
+BoolOption
+~~~~~~~~~~
+
 .. autoclass:: BoolOption
     :private-members:
 
+IntOption
+~~~~~~~~~
+
 .. autoclass:: IntOption
     :private-members:
 
+FloatOption
+~~~~~~~~~~~
+
 .. autoclass:: FloatOption
     :private-members:
 
+StrOption
+~~~~~~~~~
+
 .. autoclass:: StrOption
     :private-members:
 
+UnicodeOption
+~~~~~~~~~~~~~
+
+.. autoclass:: UnicodeOption
+    :private-members:
+
+SymLinkOption
+~~~~~~~~~~~~~
 
 .. autoclass:: SymLinkOption
-
+    :private-members:
-    .. automethod:: __init__
 
 
 ``SymLinkOption`` redirects to another configuration option in the
@@ -52,19 +71,41 @@ configuration, that is :
 - retrieves the value of the target,
 - can set the value of the target too
 
+IPOption
+~~~~~~~~
 
 .. autoclass:: IPOption
+    :private-members:
+
+PortOption
+~~~~~~~~~~
+
+.. autoclass:: PortOption
+    :private-members:
+
+NetmaskOption
+~~~~~~~~~~~~~
 
 .. autoclass:: NetmaskOption
+    :private-members:
+
+NetworkOption
+~~~~~~~~~~~~~
 
 .. autoclass:: NetworkOption
+    :private-members:
+
+DomainnameOption
+~~~~~~~~~~~~~~~~
 
 .. autoclass:: DomainnameOption
+    :private-members:
 
+ChoiceOption
+~~~~~~~~~~~~
 
 .. autoclass:: ChoiceOption
-
+    :private-members:
-    .. automethod:: __init__
 
 
 .. _optdescr:

doc/storage.txt

@@ -1,18 +1,12 @@
 Storage
 =======
 
-Config's informations are, by default, volatiles. This means, all values and
-settings changes will be lost.
-
-The storage is the system Tiramisu uses to communicate with various DB.
-You can specified a persistent storage.
-
-.. image:: storage.png
-
 .. automodule:: tiramisu.storage
 
 .. automethod:: tiramisu.storage.set_storage
 
+.. image:: storage.png
+
 Dictionary
 ~~~~~~~~~~
 
@@ -49,4 +43,10 @@ Example
 >>> c2 = Config(o, persistent=True, session_id='xxxx')
 >>> c2.str
 'yes'
+>>> del(c2)
+>>> list_sessions()
+['xxxx']
+>>> delete_session('xxxx')
+>>> c3 = Config(o, persistent=True, session_id='xxxx')
+>>> c3.str
 

tiramisu/option.py

@@ -319,7 +319,7 @@ class Option(BaseOption):
     """
     Abstract base class for configuration option's.
 
-    Reminder: an Option object is **not** a container for the value
+    Reminder: an Option object is **not** a container for the value.
     """
     __slots__ = ('_multi', '_validator', '_default_multi', '_default',
                  '_callback', '_multitype', '_master_slaves', '__weakref__')
@@ -342,9 +342,10 @@ class Option(BaseOption):
         :param callback: the name of a function. If set, the function's output
                          is responsible of the option's value
         :param callback_params: the callback's parameter
-        :param validator: the name of a function wich stands for a custom
+        :param validator: the name of a function which stands for a custom
                           validation of the value
         :param validator_args: the validator's parameters
+        :param properties: tuple of default properties
 
         """
         super(Option, self).__init__(name, doc, requires, properties)

tiramisu/storage/__init__.py

@@ -19,7 +19,13 @@
 # the whole pypy projet is under MIT licence
 # ____________________________________________________________
 
-"""Storage is basic components used to set Config informations in DB.
+"""Config's informations are, by default, volatiles. This means, all values and
+settings changes will be lost.
+
+The storage is the system Tiramisu uses to communicate with various DB.
+You can specified a persistent storage.
+
+Storage is basic components used to set Config informations in DB.
 The primary "entry point" class is the StorageType and it's public
 configurator ``set_storage()``.
 """