refactoring doc for the new API

doc/config.txt

@@ -5,11 +5,7 @@ Configuration handling basics
 ===============================
 
 `Config` and `Option` objects
-=========================================
-
-
-Take a look at `test_config.test_base_config()` or
-`test_config.test_base_config_and_groups()`.
+================================
 
 Accessing the configuration `Option`'s
 -----------------------------------------
@@ -48,7 +44,8 @@ option has a name, as does every option group. The parts of the full
 name of the option are separated by dots: e.g.
 ``config.optgroup.optname``.
 
-**Can you repeat it, what is the protocol of accessing a config's attribute ?**
+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,
 
@@ -104,9 +101,90 @@ the first one is of course the `__setattr__` method
 
     cfg.name = value
 
-wich has the same effect that the "global" `set()` method : it expects that
-the value owner is the default `glossary#valueowner`
+wich has the same effect that the "global" `set()` method (it expects that
+the value owner is the default)
 
 ::
 
      cfg.set(name=value)
+
+.. module:: tiramisu.config
+
+The handling of options is split into two parts: the description of
+which options are available, what their possible values and defaults are
+and how they are organized into a tree. A specific choice of options is
+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).
+
+The configuration object important methods
+---------------------------------------------
+
+`config.Config()` object that lives in `config.py` hold the
+choosen values for the options (or the default value for the
+`option.Option()` object, if no choice was made).
+
+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``:
+
+.. currentmodule:: tiramisu.config
+
+.. autoclass:: Config
+
+    .. automethod:: __init__
+
+    .. rubric:: Methods
+
+    .. autosummary::
+
+      ~Config.__init__
+      ~Config.set
+
+    .. automethod:: set
+
+We can see that values can also be config objects, it's the
+sub-namespaces that are stored in the values as `Config()` objects.
+
+convenience utilities (iteration, exports...)
+-----------------------------------------------
+
+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.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.
+
+**iteration utilities**
+
+.. autoclass:: Config
+
+    .. automethod:: __init__
+
+    .. rubric:: Methods
+
+    .. autosummary::
+
+      ~Config.get
+      ~Config.find
+      ~Config.find_first
+      ~Config.getpaths
+      ~Config.iter_groups
+      ~Config.__iter__
+
+    .. automethod:: get
+    .. automethod:: find
+    .. automethod:: find_first
+    .. automethod:: getpaths
+    .. automethod:: iter_groups
+    .. automethod:: __iter__

doc/configapi.txt

@@ -1,104 +0,0 @@
-.. default-role:: literal
-
-.. module:: tiramisu.config
-
-`tiramisu.config`, the configuration management main entry
-================================================================
-
-The handling of options is split into two parts: the description of
-which options are available, what their possible values and defaults are
-and how they are organized into a tree. A specific choice of options is
-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).
-
-The configuration object important methods
----------------------------------------------
-
-`config.Config()` object that lives in `config.py` hold the
-choosen values for the options (or the default value for the
-`option.Option()` object, if no choice was made).
-
-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``:
-
-.. currentmodule:: tiramisu.config
-
-.. autoclass:: Config
-
-    .. automethod:: __init__
-
-    .. rubric:: Methods
-
-    .. autosummary::
-
-      ~Config.__init__
-      ~Config.set
-      ~Config.setoption
-
-    .. automethod:: set
-    .. automethod:: setoption
-
-Here are some private attributes of a `Config()` object, for a
-comprehension of the internal merchanism:
-
-- `_cfgimpl_descr =` `option.OptionDescription()`,
-  e.g. the :ref:`optdescr`
-
-- `_cfgimpl_values` contains the `option.Option()`'s values.
-  Yes, the values of the options: remember that the values are stored **inside**
-  the `config.Config()` and not in the `Option()`
-
-`_cfgimpl_values` contains something like that
-
-::
-
-    {'int': 0, 'wantframework': False, 'objspace': 'std', 'bool': False,
-    'str': 'abc', 'wantref': False}
-
-We can see that values can also be config objects, it's the
-sub-namespaces that are stored in the values as `Config()` objects.
-
-convenience utilities (iteration, exports...)
------------------------------------------------
-
-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.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.
-
-**iteration utilities**
-
-.. autoclass:: Config
-
-    .. automethod:: __init__
-
-    .. rubric:: Methods
-
-    .. autosummary::
-
-      ~Config.get
-      ~Config.find
-      ~Config.find_first
-      ~Config.getpaths
-      ~Config.iter_groups
-      ~Config.__iter__
-
-    .. automethod:: get
-    .. automethod:: find
-    .. automethod:: find_first
-    .. automethod:: getpaths
-    .. automethod:: iter_groups
-    .. automethod:: __iter__

doc/getting-started.txt

@@ -1,5 +1,5 @@
 ==================================
-Tiramisu - getting started
+Getting started
 ==================================
 
 What is Configuration handling ?

doc/index.txt

@@ -32,7 +32,6 @@ configuration handler.
 
     getting-started
     config
-    configapi
     option
     status
     consistency

doc/status.txt

@@ -1,5 +1,8 @@
 .. default-role:: literal
 
+
+.. TODO: STATUS and settings explained
+
 Configuration status
 ======================