diff --git a/.gitignore b/.gitignore
index 77fa001..9da49a7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,5 @@
data/
+.*.swp
*.pyc
*.egg-info/
.coverage
diff --git a/ddportfolioservice/controllers/ddportfolio.py b/ddportfolioservice/controllers/ddportfolio.py
index e6bbdb3..4af5597 100644
--- a/ddportfolioservice/controllers/ddportfolio.py
+++ b/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'),
diff --git a/ddportfolioservice/model/__init__.py b/ddportfolioservice/model/__init__.py
index f5029b6..a533c8d 100644
--- a/ddportfolioservice/model/__init__.py
+++ b/ddportfolioservice/model/__init__.py
@@ -20,3 +20,7 @@
# License along with this program. If not, see
# .
#
+"""
+Model classes and model related utilities for the Debian Member Portfolio
+service.
+"""
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 0000000..567609b
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1 @@
+build/
diff --git a/docs/index.rst b/docs/index.rst
deleted file mode 100644
index 39a38d5..0000000
--- a/docs/index.rst
+++ /dev/null
@@ -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`
-
diff --git a/docs/conf.py b/docs/source/conf.py
similarity index 96%
rename from docs/conf.py
rename to docs/source/conf.py
index ce686a8..8eb44c9 100644
--- a/docs/conf.py
+++ b/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:
diff --git a/docs/source/credits.rst b/docs/source/credits.rst
new file mode 100644
index 0000000..74e2dd2
--- /dev/null
+++ b/docs/source/credits.rst
@@ -0,0 +1,22 @@
+Credits
+=======
+
+The Debian Member Portfolio Service contains contributions from several people.
+
+Code
+----
+
+ * Jan Dittberner
+ * Paul Wise
+
+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.
+
diff --git a/docs/source/devdocs.rst b/docs/source/devdocs.rst
new file mode 100644
index 0000000..a07365c
--- /dev/null
+++ b/docs/source/devdocs.rst
@@ -0,0 +1,168 @@
+Development of Debian Member Portfolio Service
+==============================================
+
+The Debian Member Portfolio Service is implemented in `Python
+`_ using the `Pylons
+`_ 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 `_::
+
+ 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 `_ 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.
+
diff --git a/docs/source/index.rst b/docs/source/index.rst
new file mode 100644
index 0000000..192332e
--- /dev/null
+++ b/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
+`_.
+
+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`
+
diff --git a/docs/source/sourcecode.rst b/docs/source/sourcecode.rst
new file mode 100644
index 0000000..55cce3f
--- /dev/null
+++ b/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:
diff --git a/setup.cfg b/setup.cfg
index 8b8db3d..6af5237 100644
--- a/setup.cfg
+++ b/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