add documentation on how to add a new URL
authorJan Dittberner <jan@dittberner.info>
Sun, 24 Feb 2013 21:52:36 +0000 (22:52 +0100)
committerJan Dittberner <jan@dittberner.info>
Sun, 24 Feb 2013 21:52:36 +0000 (22:52 +0100)
docs/source/devdocs.rst

index e82c56f..a07365c 100644 (file)
@@ -118,3 +118,51 @@ 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.
+