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):
@@ -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

@@ -5,22 +5,22 @@ Getting started
 What is options handling ?
 =================================
 
-Due to more and more available options required to set up an operating system, 
+Due to more and more available options required to set up an operating system,
-to set up compiler options, vs... it became quite annoying to hand the 
+to set up compiler options, vs... it became quite annoying to hand the
-necessary 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 was 
+new options. To circumvent these problems the configuration management was
 introduced...
 
 What is Tiramisu ?
 ===================
 
-Tiramisu is an options handler and an options controller, wich aims at 
+Tiramisu is an options handler and an options controller, wich aims at
-producing flexible and fast options access. The main advantages are its access 
+producing flexible and fast options access. The main advantages are its access
 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 options.
 
-Last but not least, options can be reached and changed according to the access 
+Last but not least, options can be reached and changed according to the access
 rules from nearly everywhere in your appliance.
 
 Just the facts
@@ -31,21 +31,21 @@ 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
 -------------------
 
-Option objects can be created in different ways. Let's perform very basic 
+Option objects can be created in different ways. Let's perform very basic
-:class:`~tiramisu.option.Option` and :class:`~tiramisu.config.Config` object 
+:class:`~tiramisu.option.Option` and :class:`~tiramisu.config.Config` object
 manipulations:
 
 ::
@@ -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 
+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 
+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
 ----------------------