doc is ready for the new api refactoring

doc/config.txt

@@ -4,8 +4,11 @@
 Configuration handling basics
 ===============================
 
-`Config` and `Option` objects
-================================
+Tiramisu is designed with three main objects :
+
+- :class:`tiramisu.config.Config` witch is the whole configuration entry point
+- :class:`tiramisu.option.Option` stands for the option type
+- :class:`tiramisu.option.OptionDescription` stands for the description (the schema)
 
 Accessing the configuration `Option`'s
 -----------------------------------------
@@ -45,7 +48,7 @@ name of the option are separated by dots: e.g.
 ``config.optgroup.optname``.
 
 Let's make the protocol of accessing a config's attribute explicit
-(because explicit is better than implicit): 
+(because explicit is better than implicit):
 
 1. If the option has not been declared, an `AttributeError` is raised,
 
@@ -62,20 +65,6 @@ What if a value has been set and `None` is to be returned again ? Don't
 worry, an option value can be "reseted" with the help of the `option.Option.reset()`
 method.
 
-If you do not want to use the pythonic way, that is the attribute access
-way to obtain the value of the configuration option, you can also search
-for it recursively in the whole config namespaces with the ``get()``
-method :
-
-::
-
-    >>> config.get('bool')
-    True
-
-To find the right option, `get()` searches recursively into the whole
-tree. For example, to find an option which is in the `gc` namespace
-there are two possibilites.
-
 If you know the path:
 
 ::
@@ -83,13 +72,6 @@ If you know the path:
     >>> config.gc.dummy
     False
 
-If you don't remember the path:
-
-::
-
-    >>> config.get('dummy')
-    False
-
 Setting the values of the options
 ----------------------------------------
 
@@ -101,13 +83,6 @@ 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)
-
-::
-
-     cfg.set(name=value)
-
 .. module:: tiramisu.config
 
 The handling of options is split into two parts: the description of
@@ -117,12 +92,8 @@ 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).
+Configuration's interesting methods
+------------------------------------------
 
 A `Config` object is informed by an `option.OptionDescription`
 instance. The attributes of the ``Config`` objects are the names of the
@@ -130,26 +101,6 @@ 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
@@ -165,7 +116,7 @@ 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**
+.. currentmodule:: tiramisu.config
 
 .. autoclass:: Config
 
@@ -175,16 +126,12 @@ To iter on groups in the same manner, use the
 
     .. 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/consistency.txt

@@ -1,6 +1,6 @@
 .. default-role:: literal
 
-The global configuration's consistency
+The global consistency
 ========================================
 
 Identical option names

doc/getting-started.txt

@@ -71,5 +71,5 @@ So by now, we have
   :class:`tiramisu.option.BoolOption()`.
 
 Configuration option objects :class:`tiramisu.config.Config()` are produced at 
-the entry points and handed down to where they are actually used. This keeps 
-configuration local but available everywhere and consistent.
+the entry point and then handed down to where they are actually used. This 
+keeps configuration local but available everywhere and consistent.

doc/glossary.txt

@@ -1,6 +1,6 @@
 .. default-role:: literal
 
-glossary
+Glossary
 ==========
 
 .. glossary::
@@ -43,8 +43,8 @@ glossary
 
     acces rules
 
-        Access rules are : `config.Config.cfgimpl_read_write()` or
-        `config.Config.cfgimpl_read_only()`, see :doc:`status`
+        Access rules are : `config.Config.read_write()` or
+        `config.Config.read_only()`, see :doc:`status`
 
 .. glossary::
 

doc/option.txt

@@ -1,7 +1,7 @@
 .. default-role:: literal
 
-The `tiramisu.option.Option` options
-======================================
+The options
+===============
 
 Description of Options
 ----------------------
@@ -20,33 +20,23 @@ The `OptionDescription` class
 
 .. module:: tiramisu.option
 
-.. autoclass: OptionDescription
+.. autoclass:: OptionDescription
+    :special-members:
+    :members:
 
-    .. automethod:: __init__
-
-    .. rubric:: Methods
-
-    .. autosummary::
-
-      ~Config.__init__
-      ~Config.set_group_type
-
-    .. automethod:: set_group_type
-
-`Options description` objects lives in the :class:`tiramisu.config.Config` attribute.
 
 If you need to access an option object, you can do it with the OptionDescription
 object. Not only the value of the option by attribute access, but the option
 object itself that lives behind the scene. It can always be accessed internally
-with the `_cfgimpl_descr` attribute of the `config` objects. For example, with a
+with the `impl_descr` attribute of the `config` objects. For example, with a
 option named `name` in a `gc` group the `name` object can be accessed like
 this::
 
-    conf._cfgimpl_descr.name
+    conf._impl_descr.name
 
 of sub configs with ::
 
-    conf.gc._cfgimpl_descr.name
+    conf.gc._impl_descr.name
 
 This is a binding. The option objects are in the `_children` config's attribute.
 
@@ -55,7 +45,7 @@ configuration option
 
 ::
 
-    conf.gc._cfgimpl_descr.dummy.freeze()
+    conf.gc._impl_descr.dummy.freeze()
 
 or to hide it, or disable it, or... anything.
 
@@ -70,7 +60,7 @@ It's the abstract base class for almost all options (except the symblink).
     :special-members:
     :members:
 
-All option types 
+All option types
 ------------------
 
 .. autoclass:: BoolOption
@@ -91,7 +81,7 @@ All option types
     .. automethod:: __init__
 
 
-``SymLinkOption`` redirects to another configuration option in the 
+``SymLinkOption`` redirects to another configuration option in the
 configuration, that is :
 
 - retrieves the value of the target,
@@ -110,6 +100,3 @@ configuration, that is :
 .. autoclass:: ChoiceOption
 
     .. automethod:: __init__
-
-
-

doc/status.txt

@@ -3,7 +3,7 @@
 
 .. TODO: STATUS and settings explained
 
-Configuration status
+The statuses
 ======================
 
 Available configuration statuses
@@ -21,7 +21,7 @@ method:
     possible to modify a disabled option.
 
     To enable read-write status, call
-    `setting.Setting.read_write()`
+    `congi.Config.read_write()`
 
 **read only status**
 
@@ -32,7 +32,7 @@ method:
     The configuration has not an access to the hidden options
     but can read the disabled options.
 
-    To enable read only status, call `setting.Setting.read_only()`
+    To enable read only status, call `config.Config.read_only()`
 
 .. csv-table:: **Configuration's statuses summary**
    :header: " ", "Hidden", "Disabled", "Mandatory"

tiramisu/option.py

@@ -108,6 +108,7 @@ class Option(BaseInformation):
         :param validator: the name of a function wich stands for a custom
                           validation of the value
         :param validator_args: the validator's parameters
+
         """
         if not valid_name(name):
             raise ValueError(_("invalid name: {0} for option").format(name))
@@ -606,14 +607,16 @@ class DomainnameOption(Option):
 
 
 class OptionDescription(BaseInformation):
-    """Config's schema (organisation, group) and container of Options"""
+    """Config's schema (organisation, group) and container of Options
+    The `OptionsDescription` objects lives in the `tiramisu.config.Config`.
+    """
     __slots__ = ('_name', '_requires', '_cache_paths', '_group_type',
                  '_properties', '_children', '_consistencies')
 
     def __init__(self, name, doc, children, requires=None, properties=None):
         """
-        :param children: is a list of option descriptions (including
-        ``OptionDescription`` instances for nested namespaces).
+        :param children: a list of options (including option descriptions)
+
         """
         if not valid_name(name):
             raise ValueError(_("invalid name: {0} for option descr").format(name))