Merge branch 'feature/devdocs' into develop

* feature/devdocs:
  add documentation on how to add a new URL
  use docs/build instead of docs/html
  move documentation sources to docs/source
  add initial development documentation
  add source reference in docs/sourcecode.rst
  add introduction text and credits file
  prepare sphinx documentation building
  ignore vim swap files
This commit is contained in:
Jan Dittberner 2013-02-24 22:53:00 +01:00
commit 23e8c7ce0e
11 changed files with 332 additions and 25 deletions

1
.gitignore vendored
View file

@ -1,4 +1,5 @@
data/ data/
.*.swp
*.pyc *.pyc
*.egg-info/ *.egg-info/
.coverage .coverage

View file

@ -37,6 +37,9 @@ log = logging.getLogger(__name__)
class DdportfolioController(BaseController): class DdportfolioController(BaseController):
"""
Main controller for the Debian Member portfolio service.
"""
_LABELS = { _LABELS = {
'overview': { 'overview': {
'label': N_('Overview'), 'label': N_('Overview'),

View file

@ -20,3 +20,7 @@
# License along with this program. If not, see # License along with this program. If not, see
# <http://www.gnu.org/licenses/>. # <http://www.gnu.org/licenses/>.
# #
"""
Model classes and model related utilities for the Debian Member Portfolio
service.
"""

1
docs/.gitignore vendored Normal file
View file

@ -0,0 +1 @@
build/

View file

@ -1,18 +0,0 @@
.. Debian Developer Portfolio Service documentation master file, created by sphinx-quickstart on Tue Jan 20 22:27:21 2009.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to Debian Developer Portfolio Service's documentation!
==============================================================
Contents:
.. toctree::
:maxdepth: 2
Indices and tables
==================
* :ref:`genindex`
* :ref:`search`

View file

@ -19,14 +19,15 @@ import sys, os
# If your extensions are in another directory, add it here. If the directory # If your extensions are in another directory, add it here. If the directory
# is relative to the documentation root, use os.path.abspath to make it # is relative to the documentation root, use os.path.abspath to make it
# absolute, like shown here. # absolute, like shown here.
#sys.path.append(os.path.abspath('.')) sys.path.append(
os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..')))
# General configuration # General configuration
# --------------------- # ---------------------
# Add any Sphinx extension module names here, as strings. They can be extensions # Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc'] extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
# Add any paths that contain templates here, relative to this directory. # Add any paths that contain templates here, relative to this directory.
templates_path = ['.templates'] templates_path = ['.templates']
@ -42,20 +43,20 @@ master_doc = 'index'
# General information about the project. # General information about the project.
project = u'Debian Developer Portfolio Service' project = u'Debian Developer Portfolio Service'
copyright = u'2009, Jan Dittberner' copyright = u'2009-2013, Jan Dittberner'
# The version info for the project you're documenting, acts as replacement for # The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the # |version| and |release|, also used in various other places throughout the
# built documents. # built documents.
# #
# The short X.Y version. # The short X.Y version.
version = '0.1' version = '0.2.18'
# The full version, including alpha/beta/rc tags. # The full version, including alpha/beta/rc tags.
release = '0.1dev' release = '0.2.18dev'
# The language for content autogenerated by Sphinx. Refer to documentation # The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages. # for a list of supported languages.
#language = None language = 'en'
# There are two options for replacing |today|: either, you set today to some # There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used: # non-false value, then it is used:

22
docs/source/credits.rst Normal file
View file

@ -0,0 +1,22 @@
Credits
=======
The Debian Member Portfolio Service contains contributions from several people.
Code
----
* Jan Dittberner <jandd at debian dot org>
* Paul Wise <pabs at debian dot org>
Translations
------------
* Jan Dittberner
* Daniel Manzano (Brazilian Portuguese)
* Izharul Haq (Indonesian)
* Stéphane Aulery (French)
If you think your name is missing please tell me (Jan Dittberner) about your
contribution and I'll add you.

168
docs/source/devdocs.rst Normal file
View file

@ -0,0 +1,168 @@
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
~~~~~~~~~~~
Debian Member Portfolio Service uses a ini style configuration file
:file:`ddportfolioservice/model/ddportfolio.ini` to configure the generated URL
patterns. The actual URL generation is done in
:py:class:`~ddportfolioservice.controllers.ddportfolio.DdportfolioController`
in the
:py:meth:`~ddportfolioservice.controllers.ddportfolio.DdportfolioController.urllist`
method.
If you want to add a new URL type you have to add a line in
:file:`ddportfolio.ini` and an entry in
:py:class:`~ddportfolioservice.controllers.ddportfolio.DdportfolioController`'s
:py:attr:`~ddportfolioservice.controllers.ddportfolio.DdportfolioController._LABELS`
dictionary. The top level dictionary keys correspond to sections in the ini
file. The dictionary values are dictionaries themselves that contain a special
key ``label`` that defines the label of the section in the output and keys for
each entry to be rendered in that section. The values in these sub-dictionaries
are strings marked for translation using the :py:func:`~pylons.i18n._` function from
:py:mod:`pylons.i18n`.
The patterns in :file:`ddportfolio.ini` can contain the following placeholders
that are filled at runtime:
================== ========================================
Placeholder Replacement
================== ========================================
%(aliothusername)s user name on `alioth.debian.org`_
%(email)s email address (URL encoded)
%(emailnoq)s email address
%(firstchar)s first character of the email address
%(forumsid)d forum user id
%(gpgfp)s GNUPG/PGP key fingerprint
%(name)s full name (i.e. John Smith)
%(username)s Debian user name
%(wikihomepage)s full name in camel case (i.e. JohnSmith)
================== ========================================
.. _alioth.debian.org: http://alioth.debian.org/
The replacement of placeholders is performed in the
:py:meth:`~ddportfolioservice.controllers.ddportfolio.DdportfolioController.urllist`
method. And uses data from the Debian keyring. Access to the pre-parsed keyring
data is performed using the
:py:func:`~ddportfolioservice.model.dddatabuilder.build_data` function of the
module :py:mod:`ddportfolioservice.model.dddatabuilder`, which uses several
helper functions from :py:mod:`ddportfolioservice.model.keyfinder` to access
the key information.

28
docs/source/index.rst Normal file
View file

@ -0,0 +1,28 @@
.. Debian Member Portfolio Service documentation master file, created by
sphinx-quickstart on Tue Jan 20 22:27:21 2009. You can adapt this file
completely to your liking, but it should at least contain the root `toctree`
directive.
Debian Member Portfolio Service
===============================
The Debian Member Portfolio Service is a web application that provides links to
information regarding the activities of a person related to the `Debian Project
<http://www.debian.org/>`_.
The service was originally implemented and is hosted by Jan Dittberner at
http://portfolio.debian.net/.
.. toctree::
:maxdepth: 2
devdocs
sourcecode
credits
Indices and tables
==================
* :ref:`genindex`
* :ref:`search`

View file

@ -0,0 +1,95 @@
Source documentation
====================
The sections below contain mostly autogenerated documentation of the source
code of the Debian Member Portfolio Service.
Controllers
-----------
.. automodule:: ddportfolioservice.controllers
:members:
ddportfolio controller
~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: ddportfolioservice.controllers.ddportfolio
:members:
error controller
~~~~~~~~~~~~~~~~
.. automodule:: ddportfolioservice.controllers.error
:members:
showformscripts controller
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: ddportfolioservice.controllers.showformscripts
:members:
template controller
~~~~~~~~~~~~~~~~~~~
.. automodule:: ddportfolioservice.controllers.template
:members:
Library code
------------
.. automodule:: ddportfolioservice.lib
:members:
app_globals
~~~~~~~~~~~
.. automodule:: ddportfolioservice.lib.app_globals
:members:
base
~~~~
.. automodule:: ddportfolioservice.lib.base
:members:
helpers
~~~~~~~
.. automodule:: ddportfolioservice.lib.helpers
:members:
Model
-----
.. automodule:: ddportfolioservice.model
:members:
dddatabuilder
~~~~~~~~~~~~~
.. automodule:: ddportfolioservice.model.dddatabuilder
:members:
form
~~~~
.. automodule:: ddportfolioservice.model.form
:members:
keyfinder
~~~~~~~~~
.. automodule:: ddportfolioservice.model.keyfinder
:members:
keyringanalyzer
~~~~~~~~~~~~~~~
.. automodule:: ddportfolioservice.model.keyringanalyzer
:members:
urlbuilder
~~~~~~~~~~
.. automodule:: ddportfolioservice.model.urlbuilder
:members:

View file

@ -6,7 +6,9 @@ tag_svn_revision = true
find_links = http://www.pylonshq.com/download/ find_links = http://www.pylonshq.com/download/
[build_sphinx] [build_sphinx]
source-dir = docs source-dir = docs/source
build-dir = docs/build
all_files = 1
[publish] [publish]
doc-dir=docs/html doc-dir=docs/html