source: main/waeup.kwarapoly/trunk/docs/source/developerdocs/developernotes.rst @ 11154

Last change on this file since 11154 was 7823, checked in by Henrik Bettermann, 13 years ago

Update docs.

File size: 9.3 KB
Line 
1Developer Notes
2***************
3
4How to setup a developer instance of the WAeUP Kofa, handle tests, docs
5etc.
6
7The new WAeUP Kofa is based on `Grok <http://grok.zope.org/>`_.
8
9Installing a developer copy
10===========================
11
12The installation is described for Linux-based computers.
13
14Preparing the system
15--------------------
16
17To create a working copy of the WAeUP Kofa we recommend use of
18`virtualenv`. You, however, need also some basic libraries, a C
19compiler and some things more.
20
21What you need (Debian/Ubuntu package names in brackets):
22
23* Python 2.6 (python2.6)
24
25  Currently, also Python2.5 is supported but we want to make use of
26  some of the 2.6 goodies in the future.
27
28
29* Python 2.6 development files (python2.6-dev)
30
31* A C-Compiler (gcc)
32
33* The C library development files (libc6-dev)
34
35* A subversion client (svn)
36
37* enscript (enscript) [optional]
38
39  This is only needed if you want test coverage reports.
40
41All these packages can be installed on Debian systems like this::
42
43  # apt-get install python2.6 python2.6-dev python2.6-dbg \
44                    gcc libc6-dev svn enscript
45
46Afterwards you should be able to enter::
47
48  $ python2.6
49
50at the commandline and get a Python prompt. Quit the interpreter
51pressing <CTRL-D>.
52
53Installing `virtualenv`
54-----------------------
55
56We recommend use of `virtualenv` to create Python sandboxes where you
57can run your code without touching any other installations.
58
59If you don't already have ``easy_install`` available, you can find the
60script to set it up on the `PEAK EasyInstall page`_.
61
62.. _`PEAK EasyInstall page`: http://peak.telecommunity.com/DevCenter/EasyInstall#installing-easy-install
63
64You need to download `ez_setup.py`_. Then, you run it like this to
65install ``easy_install`` into your system Python::
66
67  $ sudo python2.6 ez_setup.py
68
69.. _`ez_setup.py`: http://peak.telecommunity.com/dist/ez_setup.py
70
71This will make ``easy_install`` available to you.
72
73.. note:: Sometimes you have ``easy_install`` installed but you need a
74          newer version of the underlying setuptools infrastructure to
75          make Grok work. You can upgrade setuptools with::
76
77            $ sudo easy_install -U setuptools
78
79Now you can install `virtualenv` by doing (as root)::
80
81  # easy_install-2.6 virtualenv
82
83This step will fetch all needed sources from the internet and install
84`virtualenv` locally in your Python2.6 installation.
85
86
87Creating a sandbox
88------------------
89
90This step is only necessary (and recommended) if you installed
91`virtualenv` before.
92
93As a normal user you now can create a sandbox for your upcoming work
94by::
95
96  $ virtualenv --no-site-packages mysandbox
97
98where ``mysandbox`` is a directory in the filesystem where your
99sandbox will be created. `virtualenv` will also create this directory
100for you.
101
102By passing the ``no-site-packages`` switch we tell `virtualenv` to
103provide us a clean environment without any extra-packages installed
104systemwide.
105
106If you have a look into the freshly created sandbox, you will notice
107that in the ``bin/`` directory there is also
108
109You now can activate the sandbox by doing::
110
111  $ source mysandbox/bin/activate
112
113You will notice that the input prompt changes.
114
115To deactivate the sandbox at any time, enter::
116
117  $ deactivate
118
119and the prompt will be the same as before the activation.
120
121For the following steps make sure the sandbox is active.
122
123
124Creating a working place
125------------------------
126
127In the sandbox (or anywhere else) we now create our real working
128environment. To do this, we change to the sandbox and checkout the
129sources of the WAeUP Kofa from the subversion server::
130
131  $ cd mysandbox/
132  $ svn co https://svn.waeup.org/repos/main/waeup.kofa/trunk waeup-trunk
133
134where ``waeup-trunk`` is only a name we've chosen here to make clear
135where the sources come from.
136
137This command should fetch the sources of the WAeUP sources for you and
138put it in the directory ``waeup-trunk/``.
139
140Now enter the new directory::
141
142  $ cd waeup-trunk
143
144
145Preparing the build
146-------------------
147
148In the sources directory (``waeup-trunk/``) you have to prepare the
149project to fetch needed components (eggs), compile C-code parts,
150etc. This steip will not touch any external projects::
151
152  $ python2.6 bootstrap.py
153
154This will generate some directories and the ``buildout`` script in
155``bin/`` for us. This step must be executed only once for each
156instance.
157
158Now we can do the real build by triggering::
159
160  $ bin/buildout
161
162If this is your first install of some Grok-related project, this step
163will need some time as lots of sources have to be fetched, many
164components must be compiled, etc.
165
166This step must be redone whenever you change something in
167``buildout.cfg`` or ``setup.py``.
168
169Afterwards we are ready to go.
170
171
172Start the instance
173------------------
174
175You should be able now to start the created instance by doing::
176
177   $ bin/zopectl fg
178
179If you now point a browser to::
180
181   localhost:8080
182
183you should get a login pop-up, where you can login as superuser with
184``grok`` and ``grok`` as username/password.
185
186If you want to change the default credentials, have a look into
187``buildout.cfg`` where the superuser password is determined.
188
189You can stop the instance by pressing <CTRL-C>.
190
191
192
193Documentation
194=============
195
196With the :mod:`waeup.kofa` package we try to reach high standards in
197both, documentation and testing.
198
199:mod:`waeup.kofa` makes extensive use of doctests, which this way also
200become both: executable (i.e. testable) examples and documentation.
201
202Generating documentation
203------------------------
204
205We use the excellent `Sphinx <http://sphinx.pocoo.org/>`_ Python
206documentation generator to generate the docs as HTML pages.
207
208The documentation of the :mod:`waeup.kofa` project can easily be
209created doing::
210
211  $ bin/waeupdocs
212
213This will create a tree of HTML pages in
214``parts/waeupdocs/waeup.kofa/build/waeup.kofa/`` which you can for
215instance browse by pointing your browser to this location.
216
217An 'official' place in internet for the whole docs is about to come
218but not yet available.
219
220
221Writing documentation
222---------------------
223
224means explaining to other developers what your code does and test it
225at the same time. See the many .txt files in the :mod:`waeup.kofa`
226package for examples.
227
228
229Testing
230=======
231
232Tests are most important to the reliability of the :mod:`waeup.kofa`
233package. We don't tell someone that our code works, if we cannot prove
234it. And we prove it by testing.
235
236Running tests
237-------------
238
239You can run all the tests for the package by doing::
240
241  $ bin/test
242
243If you like colored output (can improve readability of failure
244messages), use the ``-c`` switch::
245
246  $ bin/test -c
247
248We have many tests in the :mod:`waeup.kofa` package so that sometimes
249you only want the functional *or* the unit tests to run. This can be
250done like this::
251
252  $ bin/test -c -u
253
254if you want only unit tests or like this::
255
256  $ bin/test -c -f
257
258if you only want functional tests.
259
260
261Writing tests
262-------------
263
264Is a wiiide topic. For now, please see the numerous .txt files in the
265source. Most of the **are** tests.
266
267Generally, we use `z3c.testsetup` for finding and setting up tests.
268
269There are mainly two kinds of tests we use:
270
271* unit- or simple doctests
272
273  These are included in test runs automatically, if they provide a
274  marker like this somewhere (normally near top of file)::
275
276    .. :doctest:
277
278  Most unit tests furthermore declare that they want to be run inside
279  the `WAeUPKofaUnitTestLayer` defined in `waeup.kofa.testing`. This
280  layer groks the whole `waeup.kofa` package, so that all ZCA
281  components are already setup when you start your tests.
282 
283  To declare that a unit test testfile should be run inside this
284  layer, the testfile has to provide the following line::
285
286    .. :layer: waeup.kofa.testing.WAeUPKofaUnitTestLayer
287
288  Use it, if in your tests you make use of registered components like
289  utilities, adapters and the like.
290
291* integration or functional tests
292
293  These provide a full-blown ZODB storage, so that we can emulate
294  browser requests to the whole system. Functional tests are much more
295  expensive in terms of memory and runtime but needed, if you want to
296  test UI components.
297
298  A testfile is registered as functional test on testruns when it
299  provides a line like the following::
300
301    :Test-Layer: functional
302
303
304Code coverage
305-------------
306
307We want to make sure, that all aspects of our software are
308tested. This means, that all parts of the codes should be tested
309somewhere.
310
311To tell how good our test coverage is, we can also use the testrunner
312(``bin/test``)::
313
314  $ bin/test --coverage=coverage
315
316will run the tests but also look, which parts of code were touched by
317them. For releases we want 100% coverage. Beware: running tests with
318the ``--coverage`` switch slows down tests by factor 10 or more.
319
320The command above will output a table with percentages. Furthermore,
321in ``/parts/test/coverage`` you will (after the testrun) find your
322sources preceeded by markers which tell, how often (or none) a certain
323line was used in tests.
324
325To have a more convenient cmdline interface, we also provide some
326shortcuts::
327
328  $ bin/coverage-detect
329
330will run all the tests as shown above and put the results in
331``parts/coverage-detect/coverage``.
332
333After that you can run::
334
335  $ bin/coveragereport
336
337to get a browsable HTML representation of test coverage in
338``coverage-report/`` subdir.
339
340Both, the coverage reports and HTML documentation generated by sphinx
341can be packed and put onto a website as-is.
342
343It is also possible to generate the docs and reports nightly by a
344buildbot or something like this.
Note: See TracBrowser for help on using the repository browser.