add initial development documentation

This commit is contained in:
Jan Dittberner 2013-02-24 22:04:55 +01:00
parent 599f10a6bb
commit 4304c425f7
3 changed files with 122 additions and 0 deletions

1
docs/.gitignore vendored Normal file
View file

@ -0,0 +1 @@
html/

120
docs/devdocs.rst Normal file
View file

@ -0,0 +1,120 @@
Development of Debian Member Portfolio Service
==============================================
The Debian Member Portfolio Service is implemented in `Python
<http://www.python.org>`_ using the `Pylons
<http://docs.pylonsproject.org/en/latest/docs/pylons.html>`_ web application
framework.
The following sections describe how to setup a local development environment
for the Debian Member Portfolio Service.
All instructions assume that you work on a Debian system. You should use Python
2.7 for development.
Setup of a local development
----------------------------
To start working on the source code you need to have `git`_ installed::
sudo aptitude install git
.. _git: http://www.git-scm.com/
The canonical git repository for the Debian Member Portfolio Service is
available at http://debianstuff.dittberner.info/git/ddportfolioservice.git. To
get a clone of the source code you change to a directory of your choice and
invoke git clone::
cd ~/src
git clone http://debianstuff.dittberner.info/git/ddportfolioservice.git
You should use `virtualenv`_ to separate the development environment from your
system wide Python installation. You can install virtualenv using::
sudo aptitude install python-virtualenv
.. _virtualenv: https://pypi.python.org/pypi/virtualenv
When you have :command:`virtualenv` installed you should create a virtual
environment for Debian Member Portfolio Service development and install the
requirements using `pip <https://pypi.python.org/pypi/pip>`_::
mkdir ~/.virtualenvs
virtualenv --distribute ~/.virtualenvs/dmportfolio
. ~/.virtualenvs/dmportfolio/bin/activate
cd ~/src/ddportfolioservice
pip install -r squeezereq.pip
.. note::
The Debian Member Portfolio Service instance at http://portfolio.debian.net/
is running on a Debian Squeeze server, therefore :file:`squeezereq.pip`
contains dependency versions matching that Debian release.
The dependency download and installation into the virtual environment takes
some time.
After you have your virtual environment ready you need to setup the project for
development::
python setup.py develop
Debian Member Portfolio Service needs the JQuery JavaScript library to function
properly. The JQuery library is not included in the git clone and must be
copied into the subdirectory
:file:`ddportfolioservice/public/javascript/jquery`. On Debian systems you can
install the package libjs-jquery and place a symlink to the directory
:file:`/usr/share/javascript` into :file:`ddportfolioservice/public`: ::
sudo aptitude install libjs-jquery
ln -s /usr/share/javascript ddportfolioservice/public
Prepare for first startup
~~~~~~~~~~~~~~~~~~~~~~~~~
The Debian Member Portfolio Service uses data from the Debian keyring to get
information regarding PGP keys and names related to email addresses. Before you
can run the service you need to fetch a copy of the keyring and prepare it for
use by the code.
.. note::
You need rsync and gnupg for these tasks::
sudo aptitude install rsync gnupg
When you have both installed you can run::
. ~/.virtualenvs/dmportfolio/bin/activate
./synckeyrings.sh
python ddportfolioservice/model/keyringanalyzer.py
The first synchronizes the keyrings in :file:`$HOME/debian/keyring.debian.org`
with files on the `keyring.debian.org <http://keyring.debian.org>`_ host. And
the second generates a key/value database in
:file:`ddportfolioservice/model/keyringcache` that is used by the code.
Run a development server
~~~~~~~~~~~~~~~~~~~~~~~~
Pylons uses PasteScript to run a development server. You can run a development
server using::
paster serve --reload development.ini
The output of this command should look like the following::
Starting subprocess with file monitor
Starting server in PID 31377.
serving on http://127.0.0.1:5000
You can now access your development server at the URL that is printed by the command.
If you want to stop the development server press :kbd:`Ctrl + C`.
Common development tasks
------------------------
Add new URL
~~~~~~~~~~~

View file

@ -16,6 +16,7 @@ http://portfolio.debian.net/.
.. toctree::
:maxdepth: 2
devdocs
sourcecode
credits