From 9efe6a7b2812bb96cee27fe8ba9932fc152e87d0 Mon Sep 17 00:00:00 2001 From: Jan Dittberner Date: Sun, 24 Feb 2013 21:50:56 +0100 Subject: [PATCH 1/8] ignore vim swap files --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 77fa001..9da49a7 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ data/ +.*.swp *.pyc *.egg-info/ .coverage From 98b7bc26762b99db24d2f7f5013fc3e2626e5faa Mon Sep 17 00:00:00 2001 From: Jan Dittberner Date: Sun, 24 Feb 2013 21:56:02 +0100 Subject: [PATCH 2/8] prepare sphinx documentation building * docs/conf.py: - add sphinx.ext.viewcode to extensions - update copyright years - bump version numbers - explicitly define language * setup.cfg - define output directory and add all_files directive --- docs/conf.py | 10 +++++----- setup.cfg | 2 ++ 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index ce686a8..b2c9a85 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -26,7 +26,7 @@ import sys, os # 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 +42,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/setup.cfg b/setup.cfg index 8b8db3d..3b1d4d5 100644 --- a/setup.cfg +++ b/setup.cfg @@ -7,6 +7,8 @@ find_links = http://www.pylonshq.com/download/ [build_sphinx] source-dir = docs +build-dir = docs/html +all_files = 1 [publish] doc-dir=docs/html From b000e08b3f3f07a48ee611c3c26a0c3b6228f755 Mon Sep 17 00:00:00 2001 From: Jan Dittberner Date: Sun, 24 Feb 2013 21:59:19 +0100 Subject: [PATCH 3/8] add introduction text and credits file --- docs/credits.rst | 22 ++++++++++++++++++++++ docs/index.rst | 20 ++++++++++++++------ 2 files changed, 36 insertions(+), 6 deletions(-) create mode 100644 docs/credits.rst diff --git a/docs/credits.rst b/docs/credits.rst new file mode 100644 index 0000000..74e2dd2 --- /dev/null +++ b/docs/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/index.rst b/docs/index.rst index 39a38d5..28d90aa 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,15 +1,23 @@ -.. 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. +.. 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. -Welcome to Debian Developer Portfolio Service's documentation! -============================================================== +Debian Member Portfolio Service +=============================== -Contents: +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 + credits + Indices and tables ================== From 599f10a6bb9fed2de09455556255e79b8de2623f Mon Sep 17 00:00:00 2001 From: Jan Dittberner Date: Sun, 24 Feb 2013 22:01:32 +0100 Subject: [PATCH 4/8] add source reference in docs/sourcecode.rst * ddportfolioservice/controllers/ddportfolio.py - add docstring to DdportfolioController * ddportfolioservice/model/__init__.py - add module docstring * docs/index.rst - add link to sourcecode file * docs/sourcecode.rst - include autogenerated module information --- ddportfolioservice/controllers/ddportfolio.py | 3 + ddportfolioservice/model/__init__.py | 4 + docs/index.rst | 1 + docs/sourcecode.rst | 95 +++++++++++++++++++ 4 files changed, 103 insertions(+) create mode 100644 docs/sourcecode.rst 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/index.rst b/docs/index.rst index 28d90aa..aadf843 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,6 +16,7 @@ http://portfolio.debian.net/. .. toctree:: :maxdepth: 2 + sourcecode credits Indices and tables diff --git a/docs/sourcecode.rst b/docs/sourcecode.rst new file mode 100644 index 0000000..55cce3f --- /dev/null +++ b/docs/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: From 4304c425f76f8b320fdd968d9a9843b4dd1c6ea8 Mon Sep 17 00:00:00 2001 From: Jan Dittberner Date: Sun, 24 Feb 2013 22:04:55 +0100 Subject: [PATCH 5/8] add initial development documentation --- docs/.gitignore | 1 + docs/devdocs.rst | 120 +++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 3 files changed, 122 insertions(+) create mode 100644 docs/.gitignore create mode 100644 docs/devdocs.rst diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..5ccff1a --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +html/ diff --git a/docs/devdocs.rst b/docs/devdocs.rst new file mode 100644 index 0000000..e82c56f --- /dev/null +++ b/docs/devdocs.rst @@ -0,0 +1,120 @@ +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 +~~~~~~~~~~~ diff --git a/docs/index.rst b/docs/index.rst index aadf843..192332e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,6 +16,7 @@ http://portfolio.debian.net/. .. toctree:: :maxdepth: 2 + devdocs sourcecode credits From f778c21b0e61c0ea810d718c5d475b8953d7ba80 Mon Sep 17 00:00:00 2001 From: Jan Dittberner Date: Sun, 24 Feb 2013 22:13:12 +0100 Subject: [PATCH 6/8] move documentation sources to docs/source * docs/source/conf.py - add toplevel directory to Python search path to allow building of documentation using system sphinx installation --- docs/{ => source}/conf.py | 3 ++- docs/{ => source}/credits.rst | 0 docs/{ => source}/devdocs.rst | 0 docs/{ => source}/index.rst | 0 docs/{ => source}/sourcecode.rst | 0 setup.cfg | 2 +- 6 files changed, 3 insertions(+), 2 deletions(-) rename docs/{ => source}/conf.py (98%) rename docs/{ => source}/credits.rst (100%) rename docs/{ => source}/devdocs.rst (100%) rename docs/{ => source}/index.rst (100%) rename docs/{ => source}/sourcecode.rst (100%) diff --git a/docs/conf.py b/docs/source/conf.py similarity index 98% rename from docs/conf.py rename to docs/source/conf.py index b2c9a85..8eb44c9 100644 --- a/docs/conf.py +++ b/docs/source/conf.py @@ -19,7 +19,8 @@ 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 # --------------------- diff --git a/docs/credits.rst b/docs/source/credits.rst similarity index 100% rename from docs/credits.rst rename to docs/source/credits.rst diff --git a/docs/devdocs.rst b/docs/source/devdocs.rst similarity index 100% rename from docs/devdocs.rst rename to docs/source/devdocs.rst diff --git a/docs/index.rst b/docs/source/index.rst similarity index 100% rename from docs/index.rst rename to docs/source/index.rst diff --git a/docs/sourcecode.rst b/docs/source/sourcecode.rst similarity index 100% rename from docs/sourcecode.rst rename to docs/source/sourcecode.rst diff --git a/setup.cfg b/setup.cfg index 3b1d4d5..e1069a2 100644 --- a/setup.cfg +++ b/setup.cfg @@ -6,7 +6,7 @@ tag_svn_revision = true find_links = http://www.pylonshq.com/download/ [build_sphinx] -source-dir = docs +source-dir = docs/source build-dir = docs/html all_files = 1 From 1fc616adf73950139c6ad0e88f275a936fdc88ff Mon Sep 17 00:00:00 2001 From: Jan Dittberner Date: Sun, 24 Feb 2013 22:25:23 +0100 Subject: [PATCH 7/8] use docs/build instead of docs/html --- docs/.gitignore | 2 +- setup.cfg | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/.gitignore b/docs/.gitignore index 5ccff1a..567609b 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1 +1 @@ -html/ +build/ diff --git a/setup.cfg b/setup.cfg index e1069a2..6af5237 100644 --- a/setup.cfg +++ b/setup.cfg @@ -7,7 +7,7 @@ find_links = http://www.pylonshq.com/download/ [build_sphinx] source-dir = docs/source -build-dir = docs/html +build-dir = docs/build all_files = 1 [publish] From 9706f2777c7f3cf2135febe98cb40ad1bca64d08 Mon Sep 17 00:00:00 2001 From: Jan Dittberner Date: Sun, 24 Feb 2013 22:52:36 +0100 Subject: [PATCH 8/8] add documentation on how to add a new URL --- docs/source/devdocs.rst | 48 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/docs/source/devdocs.rst b/docs/source/devdocs.rst index e82c56f..a07365c 100644 --- a/docs/source/devdocs.rst +++ b/docs/source/devdocs.rst @@ -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. +