automatic API documentation

doc/config.txt

@@ -1,7 +1,7 @@
 .. default-role:: literal
 
 ===============================
-Configuration handling basics
+Options handling basics
 ===============================
 
 Tiramisu is made of almost three main objects :
@@ -10,8 +10,8 @@ Tiramisu is made of almost three main objects :
 - :class:`tiramisu.option.Option` stands for the option types
 - :class:`tiramisu.option.OptionDescription` is the shema, the option's structure
 
-Accessing the configuration `Option`'s
+Accessing the `Option`'s
------------------------------------------
+-------------------------
 
 The `Config` object attribute access notation stands for the value of the
 configuration's `Option`. That is, the `Config`'s object attribute is the name
@@ -41,11 +41,10 @@ object is returned, and if no `Option` has been declared in the
     >>> cfg.idontexist
     AttributeError: 'OptionDescription' object has no attribute 'idontexist'
 
-The configuration `Option` objects (in this case the `BoolOption`), are
+The `Option` objects (in this case the `BoolOption`), are organized into a tree
-organized into a tree into nested `OptionDescription` objects. Every
+into nested `OptionDescription` objects. Every option has a name, as does every
-option has a name, as does every option group. The parts of the full
+option group. The parts of the full name of the option are separated by dots:
-name of the option are separated by dots: e.g.
+e.g. ``cfg.optgroup.optname``.
-``config.optgroup.optname``.
 
 Let's make the protocol of accessing a config's attribute explicit
 (because explicit is better than implicit):
@@ -106,6 +105,63 @@ bundled into a configuration object which has a reference to its option
 description (and therefore makes sure that the configuration values
 adhere to the option description).
 
+
+Common manipulations
+------------------------
+
+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])
+
+let's set somme access rules on the main namespace
+
+>>> c = Config(rootod)
+>>> c.read_write()
+
+let's travel the namespaces
+
+>>> print c
+[od1]
+>>> print c.od1
+var1 = None
+var2 = value
+>>> print c.od1.var1
+None
+>>> print c.od1.var2
+value
+
+let's modify a value (careful to the value's type...)
+
+>>> c.od1.var1 = 'value'
+Traceback (most recent call last):
+[...]
+ValueError: invalid value value for option var1
+>>> c.od1.var1 = u'value'
+>>> print c.od1.var1
+value
+>>> c.od1.var2 = u'value2'
+>>> print c.od1.var2
+value2
+
+let's come back to the default value
+
+>>> del(c.od1.var2)
+>>> print c.od1.var2
+value
+
+The value is saved in a :class:`~tiramisu.value.Value` object.
+It is on this object that we have to trigger the `reset`
+
+
+
+
 Configuration's interesting methods
 ------------------------------------------
 

doc/getting-started.txt

@@ -55,22 +55,26 @@ manipulations:
     >>> descr = OptionDescription("optgroup", "", [
     ...     BoolOption("bool", "", default=False)])
     >>>
-    >>> config = Config(descr)
+    >>> c = Config(descr)
-    >>> # now we have a config, wich contains an option:
+    >>> # now we have a container, wich contains an option:
-    >>> config.bool
+    >>> c.bool
     False
-    >>> config.bool = True
+    >>> c.bool = True
-    >>> config.bool
+    >>> c.bool
     True
 
 
 So by now, we have
 
-- a namespace (which is `config` here) 
+- a namespace (which is `c` here)
 - the access of an option's value by the
   attribute access way (here `bool`, wich is a boolean option:
-  :class:`tiramisu.option.BoolOption()`.
+  :class:`~tiramisu.option.BoolOption()`.
 
 So, option objects are produced at the entry point and then handed down to
 where they are actually used. This keeps options local but available everywhere
 and consistent.
+
+The namespace is created, we can set a `read_write` access to the options::
+
+    >>> c.read_write()

doc/option.txt

@@ -1,7 +1,7 @@
 .. default-role:: literal
 
-The options
+The options types
-===============
+===================
 
 Description of Options
 ----------------------