1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
|
File and directory contents
===========================
* `lib/` contains the source code
- `pdfimposer.py` contains the python module which forms the backend
- `bookletbinder/` contains the commandline and GTK utility
* `data/` contains data for bookletbinder
* `doc/` contains some documentation
* `tests/` containts some tests scripts and their data files
Coding style
============
Please try to follow PEP 8 "Style Guide for Python Code".
Docstring conventions
=====================
Please add a docstring for each public object (module, function, class,
method, data field, ...)
As PEP 257 "Docstring conventions" is not so precise, please use the
following conventions, inspired from [OpenAlea's] [1].
We use reStructuredText for the docstrings, so we should add at the
beginning of each module:
__docformat__ = "restructuredtext"
For each docsting, the first line of the docstring must be a brief synopsis.
An optional longer explanation may follow.
It should be followed by these sections:
- "Parameters" for a function or method which takes arguments;
- "Returns" for a function or method which has a return value.
The syntax for the "parameters" section should be: 2 spaces, a dash, a
space, a backquote, argument name, a backquote, a semicolon, a space,
description.
> XXX: Put this ?
Then, add optional section using sphinx directives ".. todo::, ".. warnings::" etc.
Here is an example:
def example(arg1, arg2):
"""Brief synopsis on 1 line, COMPULSORY.
This is a longer explanation, if the function or method, which
is OPTIONAL.
:Parameters:
- `arg1`: the first value.
- `arg2`: the second value.
:Returns:
The return value.
"""
> XXX: Perhaps would it be best to use markdown, e.g. with
> [python-markdown-api-builder] [2]
[1]: http://openalea.gforge.inria.fr/dokuwiki/doku.php?id=documentation:doctests:how_to_document_python_api
[2]: http://gitorious.org/python-markdown-api-builder
|
