docstrings and api

doc/config.txt

@@ -83,7 +83,7 @@ the first one is of course the `__setattr__` method
 
     cfg.name = value
 
-And if you wanna come back to a default value, do it the pythonic way::
+And if you wanna come back to a default value, use the builtin `del()` function::
 
     del(cfg.name)
 
@@ -103,46 +103,30 @@ A `Config` object is informed by an `option.OptionDescription`
 instance. The attributes of the ``Config`` objects are the names of the
 children of the ``OptionDescription``.
 
-Here are the (useful) methods on ``Config``:
-
-
-With this `config.Config()` configuration management entry point,
-it is possible to
-
-- `iter` on config, notice that there is an iteration order wich is
-  the order of the :ref:`optdescr` specification entries,
-- compare two configs (equality),
-- export the whole config into a `dict` with `config.SubConfig.make_dict()`,
-
-`option.Option()` objects in a config are iterable in the pythonic
-way, that is something like `[(name, value) for name, value in config]`.
-
-To iter on groups in the same manner, use the
-`config.Config.iter_groups()` method wich yields generators too.
+Here are the (useful) methods on ``Config`` (or `SubConfig`).
 
 .. currentmodule:: tiramisu.config
 
-.. autoclass:: Config
+.. class:: Config
+
+.. autoclass:: SubConfig
+    :members: find, find_first, __iter__, iter_groups, iter_all, make_dict
 
     .. automethod:: __init__
+    
+    .. rubric:: Summary
+
+    .. autosummary::
+ 
+       find
+       find_first
+
+       __iter__
+       iter_groups
+       iter_all
+
+       make_dict
 
     .. rubric:: Methods
 
-    .. autosummary::
-
-      ~Config.find
-      ~Config.find_first
-      ~Config.iter_groups
-      ~Config.__iter__
-
-    .. automethod:: find
-    .. automethod:: find_first
-    .. automethod:: iter_groups
-    .. automethod:: __iter__
-
-or a SubConfig, or a MetaConfig :
-
-
-.. autoclass:: SubConfig
-    :members:
-    :special-members:
+ 

doc/index.txt

@@ -33,8 +33,8 @@ configuration handler.
     option
     status
     consistency
-    glossary
     error
+    glossary
 
 Indices and tables
 ==================

tiramisu/config.py

@@ -351,8 +351,34 @@ class SubConfig(BaseInformation):
 
     def make_dict(self, flatten=False, _currpath=None, withoption=None,
                   withvalue=None):
-        """export the whole config into a `dict`
+        """exports the whole config into a `dict`, for example: 
         
+        >>> print cfg.make_dict()
+        {'od2.var4': None, 'od2.var5': None, 'od2.var6': None}
+        
+        
+        
+        :param flatten: returns a dict(name=value) instead of a dict(path=value)
+                        ::
+
+                            >>> print cfg.make_dict(flatten=True)
+                            {'var5': None, 'var4': None, 'var6': None}
+       
+        :param withoption: returns the options that are present in the very same
+                           `OptionDescription` than the `withoption` itself::
+
+                                >>> print cfg.make_dict(withoption='var1')
+                                {'od2.var4': None, 'od2.var5': None, 'od2.var6': None, 
+                                'od2.var1': u'value', 'od1.var1': None, 
+                                'od1.var3': None, 'od1.var2': None}
+
+        :param withvalue: returns the options that have the value `withvalue`
+                          ::
+
+                            >>> print c.make_dict(withoption='var1', withvalue=u'value')
+                            {'od2.var4': None, 'od2.var5': None, 'od2.var6': None, 
+                            'od2.var1': u'value'}
+
         :returns: dict of Option's name (or path) and values
         """
         pathsvalues = []

tiramisu/value.py

@@ -25,9 +25,9 @@ from tiramisu.i18n import _
 
 
 class Values(object):
-    """`Config`'s root indeed is in charge of the `Option()`'s values,
-    and the values are physicaly located here. `Values` is also
-    responsible for a caching utility.
+    """The `Config`'s root is indeed  in charge of the `Option()`'s values,
+    but the values are physicaly located here, in `Values`, wich is also
+    responsible of a caching utility.
     """
     __slots__ = ('context', '_values', '_cache')