finalise the doc for the 1.0 release
authorgwen <gremond@cadoles.com>
Thu, 29 Aug 2013 09:48:34 +0000 (11:48 +0200)
committergwen <gremond@cadoles.com>
Thu, 29 Aug 2013 09:48:34 +0000 (11:48 +0200)
doc/config.txt
doc/consistency.txt
doc/doctest.txt
doc/getting-started.txt
doc/option.txt

index 3b24cb6..c833172 100644 (file)
@@ -13,10 +13,11 @@ Tiramisu is made of almost three main objects :
 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
-of the `Option`, and the value is the value accessed by the `__getattr__`
-attribute access mechanism.
+The :class:`~tiramisu.config.Config` object attribute access notation stands for 
+the value of the configuration's :class:`~tiramisu.option.Option`. That is, the 
+:class:`~tiramisu.config.Config`'s object attribute is the name of the option, 
+and the value is the value accessed by the `__getattr__` attribute access 
+mechanism.
 
 If the attribute of the `Config` called by `__getattr__` has not been set before
 (by the classic `__setattr__` mechanism), the default value of the `Option`
@@ -26,23 +27,27 @@ object is returned, and if no `Option` has been declared in the
 
 ::
 
+    >>> from tiramisu.config import Config 
+    >>> from tiramisu.option import BoolOption, OptionDescription
+    >>> 
     >>> gcdummy = BoolOption('dummy', 'dummy', default=False)
-    >>> gcdummy.getdefault()
+    >>> gcdummy.impl_getdefault()
     False
-    >>> descr = OptionDescription('tiramisu', '', [gcdummy])
-    >>> cfg = Config(descr)
     >>> cfg.dummy
     False
+    >>> descr = OptionDescription('tiramisu', '', [gcdummy])
+    >>> cfg = Config(descr)
     >>> cfg.dummy = True
     >>> cfg.dummy
     True
     >>> cfg.idontexist
     AttributeError: 'OptionDescription' object has no attribute 'idontexist'
 
-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``.
+The `Option` objects (in this case the :class:`~tiramisu.option.BoolOption`), 
+are organized into a tree into nested 
+:class:`~tiramisu.option.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):
@@ -59,19 +64,18 @@ Let's make the protocol of accessing a config's attribute explicit
    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.
+:term:`mandatory option`. A mandatory option is an option that must have a value 
+defined.
 
-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 know the path:
+Appart from this case, 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::
 ::
 
-    >>> config.gc.dummy
+    >>> cfg.cfgimpl_get_values().reset(gcdummy)
+    >>> cfg.dummy
     False
 
 Setting the values of the options
@@ -103,7 +107,6 @@ 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
 ------------------------
 
index 79ecd6e..4b268ed 100644 (file)
@@ -30,7 +30,6 @@ of the same type.
 For example, an :class:`option.IntOption` validator waits for an `int` object of 
 course, an :class:`option.StrOption` validator waits for an `str`, vs...
 
-
 Where are located the values
 -------------------------------
 
index 9c7c57e..be73752 100644 (file)
@@ -1,6 +1,11 @@
 Test framework
 ==================
 
+Have a look at the :file:`test` subdirectory of the project. 
+We are using py.test_ 
+
+.. _py.test: http://pytest.org/latest/
+
 
 config APIs
 -----------------
@@ -11,9 +16,86 @@ config APIs
 option APIs
 ---------------
 
+.. automodule:: test.test_option
+    :members:
+
+
+others
+----------
+
+.. automodule:: test.test_config_api
+    :members:
+
+.. automodule:: test.test_mandatory
+    :members:
+
+.. automodule:: test.test_config_big_example
+    :members:
+
+.. automodule:: test.test_option_default
+    :members:
+
+.. automodule:: test.test_option_consistency
+    :members:
 
 .. automodule:: test.test_option
     :members:
 
+.. automodule:: test.test_cache
+    :members:
+
+.. automodule:: test.test_option_setting
+    :members:
+
+.. automodule:: test.test_config
+    :members:
+
+.. automodule:: test.test_freeze
+    :members:
+
+.. automodule:: test.test_config_ip
+    :members:
+
+.. automodule:: test.test_slots
+    :members:
+
+.. automodule:: test.test_reverse_from_path
+    :members:
+
+.. automodule:: test.test_requires
+    :members:
+
+.. automodule:: test.test_option_owner
+    :members:
+
+.. automodule:: test.test_permissive
+    :members:
+
+.. automodule:: test.test_option_type
+    :members:
+
+.. automodule:: test.test_dereference
+    :members:
+
+.. automodule:: test.test_storage
+    :members:
+
+.. automodule:: test.test_option_calculation
+    :members:
+
+.. automodule:: test.test_option_with_special_name
+    :members:
+
+.. automodule:: test.test_config_domain
+    :members:
+
+.. automodule:: test.test_symlink
+    :members:
+
+.. automodule:: test.test_metaconfig
+    :members:
+
+.. automodule:: test.test_parsing_group
+    :members:
+
 
-    
index e429b46..13cc8f2 100644 (file)
@@ -5,10 +5,10 @@ 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, and so on. 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, 
+compiler options or whatever, 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 control was 
 introduced...
 
 What is Tiramisu ?
@@ -18,10 +18,8 @@ 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
-validations towards the whole options.
-
-Last but not least, options can be reached and changed according to the access
-rules from nearly everywhere in your appliance.
+validations towards the whole options. Furthermore, options can be reached and 
+changed according to the access rules from nearly everywhere in your appliance.
 
 Just the facts
 ==============
@@ -32,7 +30,7 @@ Download
 ---------
 
 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.
+We suggest using `git` if one wants to access to the current developments.
 
 ::
 
@@ -52,29 +50,32 @@ manipulations:
 
     >>> from tiramisu.config import Config
     >>> from tiramisu.option import OptionDescription, BoolOption
+    >>> # let's create a group of options... with only one option inside
     >>> descr = OptionDescription("optgroup", "", [
     ...     BoolOption("bool", "", default=False)])
-    >>>
+    >>> # c is a namespace as well as a container for the options
     >>> c = Config(descr)
-    >>> #┬ánow we have a container, wich contains an option:
     >>> c.bool
     False
     >>> c.bool = True
     >>> c.bool
     True
 
-
-So by now, we have
+So by now, we have:
 
 - 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:
+  attribute access way (here `bool`, wich is a boolean option 
   :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
-and consistent.
+So, option objects are produced at the entry point `c` and then handed down to 
+where they are actually used when `c.bool` is triggered. This keeps options 
+local but available at any timer and consistent.
 
-The namespace is created, we can set a `read_write` access to the options::
+Once the namespace is created, we can set a 
+:meth:`~config.CommonConfig.read_write()` access to the options::
 
     >>> c.read_write()
+
+which enables us to set a bunch of access rules that we wil explain later in 
+:doc:`status`.
index cdc5585..90dea0a 100644 (file)
@@ -1,5 +1,7 @@
 .. default-role:: literal
 
+.. module:: tiramisu.option
+
 The options types
 ===================
 
@@ -12,24 +14,6 @@ Most constructors take a ``default`` argument that specifies the default
 value of the option. If this argument is not supplied the default value
 is assumed to be ``None``.
 
-
-.. _optdescr:
-
-The `OptionDescription` class
--------------------------------
-
-.. module:: tiramisu.option
-
-.. autoclass:: OptionDescription
-    :special-members:
-    :members:
-
-
-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. 
-The option objects are in the `_children` `OptionDescription`'s attribute.
-
 The `Option` base class
 -------------------------
 
@@ -83,3 +67,18 @@ configuration, that is :
     .. automethod:: __init__
 
 
+.. _optdescr:
+
+The `OptionDescription` class
+-------------------------------
+
+.. autoclass:: OptionDescription
+    :special-members:
+    :members:
+
+
+If you need to access to 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. The option objects are in the `_children` 
+`OptionDescription`'s attribute.