Add databases doc.
[infos-pratiques:etalage.git] / docs / presentation.rst
1 Etalage presentation
2 ====================
3
4 Etalage is a part of `Comarquage.fr`_ solution.
5
6 It is the cartographic front-end page. Providing a **widget** wich can be implemented on any web pages of any websites
7 despite technologies used.
8
9 .. _Comarquage.fr: http://www.comarquage.fr
10
11
12 Structure
13 ---------
14
15 This project don't use any known framework. It's structure diverge from pylons/pyramid project byt everything used in
16 the project is writen within the project.
17
18 Metadata files:
19
20 * COPYING
21 * README.md
22
23 Then, distutils files:
24
25 * setup.cfg
26 * setup.py
27
28 In those two files, you'll find usefull informations, and most important the **entry point**
29 This **entry point** will be followed my Apache mod_wsgi::
30
31     entry_points = """
32         [paste.app_factory]
33         main = etalage.application:make_app
34         """,
35
36 This lead us in file `etalage/application.py` where the **make_app** method take configuration file in parameter and
37 ubild a WSGI Middlewares pipe.
38
39 .. FIXME Explain middleware pipes or find a link to add here
40
41 Environment
42 -----------
43
44 In the **make_app** method, you'll find a particular call to **load_environment**.
45
46 This functions consists of a big `biryani <http://gitorious.org/biryani>`_ converter wich transform raw configuration
47 variables into a clean dict with usable values. It'll ensure that every information needed is correctly given to the
48 process in order to run correctly.
49
50 A second converter is called in case some configuration variable had to be computed with previous ones.
51
52 In the same files you'll find logging, errors handler, templates and databases configurations, all set globally in
53 **Etalage modules**
54
55 * Errors are using the standard **weberror ErrorMiddleware**
56 * Logging configuration uses the standart **logging** module of python
57 * Templates uses `**Mako templates** <http://www.makotemplates.org/>`_
58 * Databases uses… see the next pages about databases.
59
60
61 Specific important files
62 ------------------------
63
64 Some file are very important in the project, knowing them can save you a large amount of time !
65
66
67 development.ini
68 ~~~~~~~~~~~~~~~
69
70 This is the *default* configuration files when you're in development mode. You'll need to adjust the content to make
71 **Etalage** works but it reflect the minimal setting requirements.
72
73
74 etalage/contexts.py
75 ~~~~~~~~~~~~~~~~~~~
76
77 In this file is defined the **Context** class. This object is really important cause it will be pass in every call for
78 every method of the project.
79
80 In each **controllers**, the first instruction is to build a **Context** object calles **ctx** to acquire all request
81 data and application environement.
82
83 We use this object to store the `**Webob Request** <http://webob.readthedocs.org/en/latest/modules/webob.html>`_ itself
84 and other usefull resources like **translator** method or **session** based storage.
85
86
87 etalage/conv.py
88 ~~~~~~~~~~~~~~~
89
90 Central system of **Etalage**. All converter are regrouped in this files, it means that a lot of specific code are
91 written in it and it need to perfectly understand what a **biryani converter** is to read it.
92
93 .. FIXME Refer to biryani pages
94
95
96 etalage/urls.py
97 ~~~~~~~~~~~~~~~
98
99 You'll find **Etalage** router here. Once again, you don't have any framework in this project, the *router* too is
100 writen within the project and can be found here.
101
102
103 etalage/wsgihelpers.py
104 ~~~~~~~~~~~~~~~~~~~~~~
105
106 Set of function used to build errors responses to clients.