From d6098f353e13a49b5c3f8316b08917656b1a5222 Mon Sep 17 00:00:00 2001 From: gwen Date: Fri, 17 May 2013 12:11:14 +0200 Subject: [PATCH] refactoring doc for the new API --- doc/architecture.dia | Bin 1383 -> 0 bytes doc/config.txt | 94 ++++++++++++++++++++++++++++++++---- doc/configapi.txt | 104 ---------------------------------------- doc/getting-started.txt | 2 +- doc/index.txt | 1 - doc/status.txt | 3 ++ 6 files changed, 90 insertions(+), 114 deletions(-) delete mode 100644 doc/architecture.dia delete mode 100644 doc/configapi.txt diff --git a/doc/architecture.dia b/doc/architecture.dia deleted file mode 100644 index 35adb7e1db0385497ca83b4fd529bf4ec0fe0225..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1383 zcmV-t1(^CDiwFP!000021MOPdZreBzea}}2>PreZG)ajP*)%D-yD0k5#TM8sux|!! zF)~|OGAKEYU-~`!ANylFmX&p^i*K@mwy=Q2usoc@A!p_sQ-1sIaS~Y%%A`7pZ)}3F zZK-&a1Ue3H?7!|lTygu|?Zw+b%Qx^B8ac6GM4T?)-Pq$So4)Dy=kqy=7OBhc$?*(bv!FN48p9>TF|Mb|l-*9INvgplTTCk^4StsYpV<^v zDHz4!?W_0htJRc>8*5*66Kw>^CenmDuHwMjM5~3Mh*L^oF__>2`>s!(*5q)w;mg8B zFAHa07EY&wX<{-XbykHOCP}1Zyh6>)OdXGtj${NWwk@m{QQYe+OLolvUPkFY0jzHS zUu}n0ZfJC{y>K@y8obPPkc|hA9WB?&`=TT74?5MuNY%|=$Jxo;FHYmWygPaKUJq}X z4J&Vr^bl~x6g!+A!kG?Kx+BdtZ5lj{3$y;NRWIA^yD+O;C9=*TBDqkeaR1&I{qH|U zT}>ky+g7p1Mbok5DANy5@18A7GW?=OSrPAtD4CDO(qz_^^;sHF3@S>Np!QmkfF9Ao zjr|AST)J|w;1{}LW$mWPI>88XJ?!?bF!ES=QK~Ja31m1dV;BfX#$lw^IAn$6UsH@2 z7pw>Oj)PQ@nhZvXiL1ilw6Wztd6%ii_taqo!oDEH^B5B@b3Ct2P-CUTan=k*kMo_5 zllh=VLhk0r!%&nogM8PUBk=KY&Zja6Hi@_77?SEZ&zX9xta!Nzm28?8AeWyTb|t0y z_wS#qG?|%^vM$rnSWV>X2I;z`-#3YeB+lxvm-nrEInmJqrYPgow$f~|>`Kr^Rzp9k z=s{(AB%k-s!)H**-r8;Ac=K}Gfo?Xq+D72@AURyt4rh}Bw|q~+xE&A(%rKs)`ps1F zY*M2QwyA?Uf@>n_{+f>V;iq4c#~M~5tyzg7!l>Kx5$TeX00rkLm|ar`5#hT%=;o|b zQfeF8K9uAmAzbn7q8(BaL87sqzdw%pIcQ{*#P>QxzveHOudP*qo|&X`CJ~50Vf8qo zXF53zo%{(cIglm*Hu(!ShsY-d{+Prgp6goY{oE+Kh zq0r-jii13wgJY~Q1KweT9#21zFQaLB9(Csx2k}fC45Ts1yzF?Lo|Lw9J&05sZX?a3 z8~++&2QBZ7u-tV>E~tXELMTt4SYxQ0qV;A;eimS@KZUJuDtS;dm=uFaX>j#?q%@;L zmEvz&P7+}CYI!@Y%iBeiVaR=qgwLEVOB|4Jfkc^eO`8+R;UzQ(c0IPkdi+O85`19UTU%<~RZ~;ZWc4#rLlzKi=Jawl2S< zN&MPMm4W&^>&O?-k+eq~)G)g7gf8-jBTGzF-F=jWLIu_vf|i_qE-Ys?5} pRqmh9F@HW4%1(HW=^U&=SMT$mblqNT{O0TS;y)jktzj1~005C_uuA{{ diff --git a/doc/config.txt b/doc/config.txt index 681a4f8..63c5b38 100644 --- a/doc/config.txt +++ b/doc/config.txt @@ -5,11 +5,7 @@ Configuration handling basics =============================== `Config` and `Option` objects -========================================= - - -Take a look at `test_config.test_base_config()` or -`test_config.test_base_config_and_groups()`. +================================ Accessing the configuration `Option`'s ----------------------------------------- @@ -48,7 +44,8 @@ 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``. -**Can you repeat it, what is the protocol of accessing a config's attribute ?** +Let's make the protocol of accessing a config's attribute explicit +(because explicit is better than implicit): 1. If the option has not been declared, an `AttributeError` is raised, @@ -104,9 +101,90 @@ 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 `glossary#valueowner` +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 +which options are available, what their possible values and defaults are +and how they are organized into a tree. A specific choice of options is +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). + +A `Config` object is informed by an `option.OptionDescription` +instance. The attributes of the ``Config`` objects are the names of the +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 + +- `iter` on config, notice that there is an iteration order wich is + the order of the :ref:`optdescr` specification entries, +- compare two configs (equality), +- export the whole config into a `dict` with `config.make_dict()`, + +`option.Option()` objects in a config are iterable in the pythonic +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** + +.. autoclass:: Config + + .. automethod:: __init__ + + .. rubric:: Methods + + .. 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__ diff --git a/doc/configapi.txt b/doc/configapi.txt deleted file mode 100644 index 91bcbec..0000000 --- a/doc/configapi.txt +++ /dev/null @@ -1,104 +0,0 @@ -.. default-role:: literal - -.. module:: tiramisu.config - -`tiramisu.config`, the configuration management main entry -================================================================ - -The handling of options is split into two parts: the description of -which options are available, what their possible values and defaults are -and how they are organized into a tree. A specific choice of options is -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). - -A `Config` object is informed by an `option.OptionDescription` -instance. The attributes of the ``Config`` objects are the names of the -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 - ~Config.setoption - - .. automethod:: set - .. automethod:: setoption - -Here are some private attributes of a `Config()` object, for a -comprehension of the internal merchanism: - -- `_cfgimpl_descr =` `option.OptionDescription()`, - e.g. the :ref:`optdescr` - -- `_cfgimpl_values` contains the `option.Option()`'s values. - Yes, the values of the options: remember that the values are stored **inside** - the `config.Config()` and not in the `Option()` - -`_cfgimpl_values` contains something like that - -:: - - {'int': 0, 'wantframework': False, 'objspace': 'std', 'bool': False, - 'str': 'abc', 'wantref': False} - -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 - -- `iter` on config, notice that there is an iteration order wich is - the order of the :ref:`optdescr` specification entries, -- compare two configs (equality), -- export the whole config into a `dict` with `config.make_dict()`, - -`option.Option()` objects in a config are iterable in the pythonic -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** - -.. autoclass:: Config - - .. automethod:: __init__ - - .. rubric:: Methods - - .. 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__ diff --git a/doc/getting-started.txt b/doc/getting-started.txt index 81bf1c0..1de6ab5 100644 --- a/doc/getting-started.txt +++ b/doc/getting-started.txt @@ -1,5 +1,5 @@ ================================== -Tiramisu - getting started +Getting started ================================== What is Configuration handling ? diff --git a/doc/index.txt b/doc/index.txt index f9fb7de..add8ac0 100644 --- a/doc/index.txt +++ b/doc/index.txt @@ -32,7 +32,6 @@ configuration handler. getting-started config - configapi option status consistency diff --git a/doc/status.txt b/doc/status.txt index ceac4b2..faa3002 100644 --- a/doc/status.txt +++ b/doc/status.txt @@ -1,5 +1,8 @@ .. default-role:: literal + +.. TODO: STATUS and settings explained + Configuration status ======================