source: trunk/HACKING @ 305

Revision 305, 3.4 KB checked in by marc, 8 years ago (diff)

updated sgml file, include hacking in distro, remove DOS line endings for hacking, add french translation for desktop file, convert sgml to manpage on the fly

Line 
1NOTE: This guide is a rough reference, please take the time to read the code
2line by line, as it is not that long. It is also outdated in some parts.
3
4Abstract:
5
6    Itaka was developed in a purely Object Oriented fashion. It is designed to
7    be completely modular and each component was made so that it is independent
8    of the other to a certain extent. First there is the core loader
9    'itaka.py', which in turn loads the Console and Configuration handlers
10    ('console.py' and 'config.py'). The configuration is read and
11    loaded, and the passed to the  new instance of our Console handler.
12   
13    After that, the main GTK+ GUI 'uigtk.py' is loaded, it is totally
14    independent from any other modules, as are the Console and Configuration
15    handlers. The main GTK+ GUI only relies on the Twisted GUI reactor to
16    handle the multi threading for simultaneous running of a GTK loop and a
17    Twisted server reactor.
18
19    The GTK+ GUI then calls on the Itaka Twisted Web Server engine 'server.py'.
20    Although the base Twisted server is completely independent of any other
21    modules through its base class 'BaseHTTPServer', the classes used by the
22    GUI are not.
23   
24        This is because or ScreenshotServer needs instances of our Gui,
25        Configuration and Console engines.  This expandability is a prime
26        example of the Object Oriented nature of Itaka.  It was designed from
27        the ground up to be modular and easily expandable through inheritance.
28
29        Such modularity allows for users to develop different GUIs in other
30        toolkits such as PyObjC (Cocoa) or PyQT. In turn, those GUIs can adapt
31        BaseHTTPServer to their needs.
32
33    The HTTP server creates a resource called '/screenshot' (URL Path), which
34    in turn takes the screenshot on request.  This URL path is referenced on
35    the HTML base code in the configuration as an <img>. The screenshot
36    resource has a special render_GET() method that initiates the screenshot
37    engine 'screenshot.py'.
38
39    The screenshot engine is done entirely on GTK+ and does depend on it. It
40    has not been yet modularized, but it would not take long to implement a
41    totally different GUI for Itaka.
42
43
44Technical standards:
45    * Inter-class communication: it is done by passing instances of one class
46      to the child object that needs it. For example, the
47      HTTP server needs an instance of the GUI for widget manipulation (Logging,
48      etc.), and instance of the configuration class and an instance of the
49      Console class. Since our main Itaka core 'itaka.py' passed the main
50      instance of those classes to the GTK+ GUI, the only thing needed to do is
51      to pass an instance of the GUI class to the child-objects that need it.
52
53    * Exceptions: Itaka's exception definitions are stored in 'error.py'.
54      Inheritance should be used widely.
55
56    * Encapsulation: All of Twisted's exceptions and exceptions of
57      screenshooting code should be encapsulated with equivalent Itaka
58      exceptions.
59
60    * Documentation: Use Epytext Markup Language.
61
62    * Private methods: Methods that are _never_ going to be called outside the
63      class should be prefixed with an underscore (_).
64
65Generating Documentation:
66
67    Itaka is fully documented with Epydoc.
68
69    You can download epydoc from http://epydoc.sourceforge.net/
70
71    You can generate documentation using epydoc.
72
73        mkdir doc
74        epydoc --html -o doc -n Itaka -u "http://itaka.jardinpresente.com.ar" *.py
75
Note: See TracBrowser for help on using the repository browser.