switch from ddportfolio to debianmemberportfolio
[debianmemberportfolio.git] / docs / source / devdocs.rst
1 Development of Debian Member Portfolio Service
2 ==============================================
3
4 The Debian Member Portfolio Service is implemented in `Python
5 <http://www.python.org>`_ using the `Pylons
6 <http://docs.pylonsproject.org/en/latest/docs/pylons.html>`_ web application
7 framework.
8
9 The following sections describe how to setup a local development environment
10 for the Debian Member Portfolio Service.
11
12 All instructions assume that you work on a Debian system. You should use Python
13 2.7 for development.
14
15 Setup of a local development
16 ----------------------------
17
18 To start working on the source code you need to have `git`_ installed::
19
20   sudo aptitude install git
21
22 .. _git: http://www.git-scm.com/
23
24 The canonical git repository for the Debian Member Portfolio Service is
25 available at http://debianstuff.dittberner.info/git/debianmemberportfolio.git.
26 To get a clone of the source code you change to a directory of your choice and
27 invoke git clone::
28
29   cd ~/src
30   git clone http://debianstuff.dittberner.info/git/debianmemberportfolio.git
31
32 You should use `virtualenv`_ to separate the development environment from your
33 system wide Python installation. You can install virtualenv using::
34
35   sudo aptitude install python-virtualenv
36
37 .. _virtualenv: https://pypi.python.org/pypi/virtualenv
38
39 When you have :command:`virtualenv` installed you should create a virtual
40 environment for Debian Member Portfolio Service development and install the
41 requirements using `pip <https://pypi.python.org/pypi/pip>`_::
42
43   mkdir ~/.virtualenvs
44   virtualenv --distribute ~/.virtualenvs/dmportfolio
45   . ~/.virtualenvs/dmportfolio/bin/activate
46   cd ~/src/debianmemberportfolio
47   pip install -r wheezyreq.pip
48
49 .. note::
50
51   The Debian Member Portfolio Service instance at http://portfolio.debian.net/
52   is running on a Debian Wheezy server, therefore :file:`wheezyreq.pip`
53   contains dependency versions matching that Debian release.
54
55 The dependency download and installation into the virtual environment takes
56 some time.
57
58 After you have your virtual environment ready you need to setup the project for
59 development::
60
61   python setup.py develop
62
63 Debian Member Portfolio Service needs the JQuery JavaScript library to function
64 properly. The JQuery library is not included in the git clone and must be
65 copied into the subdirectory
66 :file:`debianmemberportfolio/public/javascript/jquery`. On Debian systems you
67 can install the package libjs-jquery and place a symlink to the directory
68 :file:`/usr/share/javascript` into :file:`debianmemberportfolio/public`: ::
69
70   sudo aptitude install libjs-jquery
71   ln -s /usr/share/javascript debianmemberportfolio/public
72
73 Prepare for first startup
74 ~~~~~~~~~~~~~~~~~~~~~~~~~
75
76 The Debian Member Portfolio Service uses data from the Debian keyring to get
77 information regarding PGP keys and names related to email addresses. Before you
78 can run the service you need to fetch a copy of the keyring and prepare it for
79 use by the code.
80
81 .. note::
82
83   You need rsync and gnupg for these tasks::
84
85     sudo aptitude install rsync gnupg
86
87 When you have both installed you can run::
88
89   . ~/.virtualenvs/dmportfolio/bin/activate
90   ./synckeyrings.sh
91   python debianmemberportfolio/model/keyringanalyzer.py
92
93 The first synchronizes the keyrings in :file:`$HOME/debian/keyring.debian.org`
94 with files on the `keyring.debian.org <http://keyring.debian.org>`_ host. And
95 the second generates a key/value database in
96 :file:`debianmemberportfolio/model/keyringcache` that is used by the code.
97
98 Run a development server
99 ~~~~~~~~~~~~~~~~~~~~~~~~
100
101 Pylons uses PasteScript to run a development server. You can run a development
102 server using::
103
104   paster serve --reload development.ini
105
106 The output of this command should look like the following::
107
108   Starting subprocess with file monitor
109   Starting server in PID 31377.
110   serving on http://127.0.0.1:5000
111
112 You can now access your development server at the URL that is printed by the command.
113
114 If you want to stop the development server press :kbd:`Ctrl + C`.
115
116 Common development tasks
117 ------------------------
118
119 Add new URL
120 ~~~~~~~~~~~
121
122 Debian Member Portfolio Service uses a ini style configuration file
123 :file:`debianmemberportfolio/model/portfolio.ini` to configure the generated URL
124 patterns. The actual URL generation is done in
125 :py:class:`~debianmemberportfolio.controllers.portfolio.DdportfolioController`
126 in the
127 :py:meth:`~debianmemberportfolio.controllers.portfolio.DdportfolioController.urllist`
128 method.
129
130 If you want to add a new URL type you have to add a line in
131 :file:`portfolio.ini` and an entry in
132 :py:class:`~debianmemberportfolio.controllers.portfolio.DdportfolioController`'s
133 :py:attr:`~debianmemberportfolio.controllers.portfolio.DdportfolioController._LABELS`
134 dictionary. The top level dictionary keys correspond to sections in the ini
135 file. The dictionary values are dictionaries themselves that contain a special
136 key ``label`` that defines the label of the section in the output and keys for
137 each entry to be rendered in that section. The values in these sub-dictionaries
138 are strings marked for translation using the :py:func:`~pylons.i18n._` function from
139 :py:mod:`pylons.i18n`.
140
141 The patterns in :file:`portfolio.ini` can contain the following placeholders
142 that are filled at runtime:
143
144 ================== ========================================
145 Placeholder        Replacement
146 ================== ========================================
147 %(aliothusername)s user name on `alioth.debian.org`_
148 %(email)s          email address (URL encoded)
149 %(emailnoq)s       email address
150 %(firstchar)s      first character of the email address
151 %(forumsid)d       forum user id
152 %(gpgfp)s          GNUPG/PGP key fingerprint
153 %(name)s           full name (i.e. John Smith)
154 %(username)s       Debian user name
155 %(wikihomepage)s   full name in camel case (i.e. JohnSmith)
156 ================== ========================================
157
158 .. _alioth.debian.org: http://alioth.debian.org/
159
160 The replacement of placeholders is performed in the
161 :py:meth:`~debianmemberportfolio.controllers.portfolio.DdportfolioController.urllist`
162 method. And uses data from the Debian keyring. Access to the pre-parsed keyring
163 data is performed using the
164 :py:func:`~debianmemberportfolio.model.dddatabuilder.build_data` function of
165 the module :py:mod:`debianmemberportfolio.model.dddatabuilder`, which uses
166 several helper functions from :py:mod:`debianmemberportfolio.model.keyfinder`
167 to access the key information.