Merge branch 'master' of ssh://git.labs.libre-entreprise.org/gitroot/tiramisu

doc/_templates/module.rst

@@ -0,0 +1,6 @@
+{{ fullname }}
+{{ underline }}
+
+.. automodule:: {{ fullname }}
+   :members:
+   :noindex:   

doc/api/tiramisu.autolib.txt

@@ -0,0 +1,6 @@
+tiramisu.autolib
+================
+
+.. automodule:: tiramisu.autolib
+   :members:
+   :noindex:   

doc/api/tiramisu.config.txt

@@ -0,0 +1,6 @@
+tiramisu.config
+===============
+
+.. automodule:: tiramisu.config
+   :members:
+   :noindex:   

doc/api/tiramisu.error.txt

@@ -0,0 +1,6 @@
+tiramisu.error
+==============
+
+.. automodule:: tiramisu.error
+   :members:
+   :noindex:   

doc/api/tiramisu.option.txt

@@ -0,0 +1,6 @@
+tiramisu.option
+===============
+
+.. automodule:: tiramisu.option
+   :members:
+   :noindex:   

doc/api/tiramisu.setting.txt

@@ -0,0 +1,5 @@
+tiramisu.setting
+================
+
+.. automodule:: tiramisu.setting
+   :members:

doc/api/tiramisu.value.txt

@@ -0,0 +1,5 @@
+tiramisu.value
+==============
+
+.. automodule:: tiramisu.value
+   :members:

doc/conf.py

@@ -41,16 +41,16 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'tiramisu'
-copyright = u'2012, gwen'
+copyright = u'2013, tiramisu team'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '0'
+version = '1'
 # The full version, including alpha/beta/rc tags.
-release = '18'
+release = '1.0RC1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -91,15 +91,7 @@ pygments_style = 'sphinx'
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'traditional'
-html_theme_options = {
-    "rightsidebar": "true",
-    "nosidebar": "false",
-    "sidebarbgcolor": "black",
-    "relbarbgcolor": "black",
-    "footerbgcolor": "black"
-    }
-
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -296,3 +288,8 @@ todo_include_todos = True
 
 extlinks = {'api': ('./api/tiramisu.%s', ""),
                 'test': ('./api/test.%s', "")}
+
+
+autosummary_generate = True
+
+

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):
@@ -61,10 +60,10 @@ Let's make the protocol of accessing a config's attribute explicit
 4. If an option is declared, and a value has been set, the returned value is
    the value of the option.
 
-But there are special exceptions. We will see later on that an option can be a 
+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 defined value. 
+:term:`mandatory option`. A mandatory option is an option that must have a defined value.
-If no value have been set yet, the value is `None`. 
+If no value have been set yet, the value is `None`.
-When the option is called to retrieve a value, an exception is raised. 
+When the option is called to retrieve a value, an exception is raised.
 
 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()`
@@ -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
 ------------------------------------------
 
@@ -123,11 +179,11 @@ Here are the (useful) methods on ``Config`` (or `SubConfig`).
     :members: find, find_first, __iter__, iter_groups, iter_all, make_dict
 
     .. automethod:: __init__
-    
+
     .. rubric:: Summary
 
     .. autosummary::
- 
+
        find
        find_first
 
@@ -139,10 +195,10 @@ Here are the (useful) methods on ``Config`` (or `SubConfig`).
 
     .. rubric:: Methods
 
- 
+
-A :class:`~config.CommonConfig` is a abstract base class. A 
+A :class:`~config.CommonConfig` is a abstract base class. A
-:class:`~config.SubConfig` is an just in time created objects that wraps an 
+:class:`~config.SubConfig` is an just in time created objects that wraps an
-::class:`~option.OptionDescription`. A SubConfig differs from a Config in the 
+::class:`~option.OptionDescription`. A SubConfig differs from a Config in the
-::fact that a config is a root object and has an environnement, a context wich 
+::fact that a config is a root object and has an environnement, a context wich
-::defines the different properties, access rules, vs... There is generally only 
+::defines the different properties, access rules, vs... There is generally only
 ::one Config, and many SubConfigs.

doc/getting-started.txt

@@ -2,26 +2,26 @@
 Getting started
 ==================================
 
-What is Configuration handling ?
+What is options handling ?
 =================================
 
-Due to more and more available configuration options required to set up
+Due to more and more available options required to set up an operating system,
-an operating system, it became quite annoying to hand the necessary
+to set up compiler options, vs... it became quite annoying to hand the
-options to where they are actually used and even more annoying to add
+necessary options to where they are actually used and even more annoying to add
-new options. To circumvent these problems the configuration management
+new options. To circumvent these problems the configuration management was
-was introduced...
+introduced...
 
 What is Tiramisu ?
 ===================
 
-Tiramisu is yet another configuration handler, wich aims at producing flexible 
+Tiramisu is an options handler and an options controller, wich aims at
-and fast configuration options access. The main advantages are its access rules 
+producing flexible and fast options access. The main advantages are its access
-and the fact that the configuration's consistency is preserved at any time, see 
+rules and the fact that the whole consistency is preserved at any time, see
-:doc:`consistency`. There is of course type and structure validations, but also 
+:doc:`consistency`. There is of course type and structure validations, but also
-validations towards the whole configuration.
+validations towards the whole options.
 
-Last but not least, configuration options can be reached and changed
+Last but not least, options can be reached and changed according to the access
-according to the access rules from nearly everywhere in your appliance.
+rules from nearly everywhere in your appliance.
 
 Just the facts
 ==============
@@ -31,21 +31,22 @@ Just the facts
 Download
 ---------
 
-To obtain a copy of the sources, check it out from the repository using `git`. 
+To obtain a copy of the sources, check it out from the repository using `git`.
 We suggest using `git` if one wants to access the current developments.
 
 ::
 
     git clone git://git.labs.libre-entreprise.org/tiramisu.git
 
-This will get you a fresh checkout of the code repository in a local directory 
+This will get you a fresh checkout of the code repository in a local directory
 named ``tiramisu``.
 
 Getting started
 -------------------
 
-Configuration option objects can be created in different ways. Let's perform 
+Option objects can be created in different ways. Let's perform very basic
-very basic :class:`tiramisu.config.Config` object manipulations:
+:class:`~tiramisu.option.Option` and :class:`~tiramisu.config.Config` object
+manipulations:
 
 ::
 
@@ -54,22 +55,26 @@ very basic :class:`tiramisu.config.Config` object 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()`.
 
-Configuration option objects :class:`tiramisu.config.Config()` are produced at 
+So, option objects are produced at the entry point and then handed down to
-the entry point and then handed down to where they are actually used. This 
+where they are actually used. This keeps options local but available everywhere
-keeps configuration local but available everywhere and consistent.
+and consistent.
+
+The namespace is created, we can set a `read_write` access to the options::
+
+    >>> c.read_write()

doc/index.txt

@@ -17,13 +17,16 @@ The tasting of `Tiramisu`
 
     is a cool, refreshing Italian dessert,
 
-    it is also a `configuration management tool`_.
+    it is also an `options controller tool`_.
 
-.. _`configuration management tool`: http://en.wikipedia.org/wiki/Configuration_management
+.. _`options controller tool`: http://en.wikipedia.org/wiki/Configuration_management#Overview
 
 
-It's a pretty small, local (that is, straight on the operating system)
+It's a pretty small, local (that is, straight on the operating system) options 
-configuration handler.
+handler and controller.
+
+controlling options explanations 
+--------------------------------------
 
 .. toctree::
     :maxdepth: 1
@@ -35,7 +38,22 @@ configuration handler.
     consistency
     error
     glossary
-    test
+    doctest
+
+
+auto generated library's API
+--------------------------------
+
+.. autosummary::
+    :toctree: api
+    :template: module.rst
+
+    tiramisu.option
+    tiramisu.setting
+    tiramisu.config
+    tiramisu.value
+    tiramisu.autolib
+    tiramisu.error
     
 Indices and tables
 ==================

doc/option.txt

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

tiramisu/config.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"pretty small and local configuration management tool"
+"options handler global entry point"
 # Copyright (C) 2012-2013 Team tiramisu (see AUTHORS for all contributors)
 #
 # This program is free software; you can redistribute it and/or modify

tiramisu/option.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"option types and option description for the configuration management"
+"option types and option description"
 # Copyright (C) 2012-2013 Team tiramisu (see AUTHORS for all contributors)
 #
 # This program is free software; you can redistribute it and/or modify