From f235986879bf709d5cfe092a203072ec43104e94 Mon Sep 17 00:00:00 2001 From: gwen Date: Fri, 23 Aug 2013 11:42:22 +0200 Subject: [PATCH] automatic API documentation --- doc/config.txt | 96 ++++++++++++++++++++++++++++++++--------- doc/getting-started.txt | 46 +++++++++++--------- doc/option.txt | 4 +- 3 files changed, 103 insertions(+), 43 deletions(-) diff --git a/doc/config.txt b/doc/config.txt index 0326e30..8f93a7a 100644 --- a/doc/config.txt +++ b/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 -organized into a tree into nested `OptionDescription` objects. Every -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``. +The `Option` objects (in this case the `BoolOption`), are organized into a tree +into nested `OptionDescription` objects. Every option has a name, as does every +option group. The parts of the full name of the option are separated by dots: +e.g. ``cfg.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 -: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`. -When the option is called to retrieve a value, an exception is raised. +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. +If no value have been set yet, the value is `None`. +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 -:class:`~config.SubConfig` is an just in time created objects that wraps an -::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 -::defines the different properties, access rules, vs... There is generally only + +A :class:`~config.CommonConfig` is a abstract base class. A +:class:`~config.SubConfig` is an just in time created objects that wraps an +::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 +::defines the different properties, access rules, vs... There is generally only ::one Config, and many SubConfigs. diff --git a/doc/getting-started.txt b/doc/getting-started.txt index aa77a1e..b1484a7 100644 --- a/doc/getting-started.txt +++ b/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, -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 -new options. To circumvent these problems the configuration management was +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 +necessary options to where they are actually used and even more annoying to add +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 -producing flexible and fast options access. The main advantages are its access +Tiramisu is an options handler and an options controller, wich aims at +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 -:class:`~tiramisu.option.Option` and :class:`~tiramisu.config.Config` object +Option objects can be created in different ways. Let's perform very basic +: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) - >>> # now we have a config, wich contains an option: - >>> config.bool + >>> c = Config(descr) + >>> # now we have a container, wich contains an option: + >>> c.bool False - >>> config.bool = True - >>> config.bool + >>> c.bool = True + >>> 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 -where they are actually used. This keeps options local but available everywhere +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 and consistent. + +The namespace is created, we can set a `read_write` access to the options:: + + >>> c.read_write() diff --git a/doc/option.txt b/doc/option.txt index 8e4cee3..981b05b 100644 --- a/doc/option.txt +++ b/doc/option.txt @@ -1,7 +1,7 @@ .. default-role:: literal -The options -=============== +The options types +=================== Description of Options ----------------------