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

.gitignore

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

ddportfolioservice/controllers/ddportfolio.py

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

ddportfolioservice/model/__init__.py

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

docs/.gitignore

@@ -0,0 +1 @@
+build/

docs/index.rst

@@ -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`
-

docs/source/conf.py

@@ -19,14 +19,15 @@ import sys, os
 # 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
 # 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
 # ---------------------
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # 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.
 templates_path = ['.templates']
@@ -42,20 +43,20 @@ master_doc = 'index'
 
 # General information about the project.
 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
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '0.1'
+version = '0.2.18'
 # 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
 # for a list of supported languages.
-#language = None
+language = 'en'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:

docs/source/credits.rst

@@ -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.
+

docs/source/devdocs.rst

@@ -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.
+

docs/source/index.rst

@@ -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`
+

docs/source/sourcecode.rst

@@ -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:

setup.cfg

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