docs/index.rst

+.. Memopol documentation master file, created by
+   sphinx-quickstart on Thu Nov 12 22:42:47 2015.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to Memopol's documentation!
+===================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   usage
+   deploy-custom
+   administration
+   scores
+   api
+   development
+   hacker
+   setup_solr
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/scores.rst

+Memopol Scores
+~~~~~~~~~~~~~~
+
+Score computation
+=================
+
+In Memopol, each representative has a score that shows how their votes match
+the recommendations made by administrators on the instance.  The total score
+of a representative is the sum of their score on each dossier, which in turn is
+the sum of their score on each proposal with a recommendation on the dossier.
+
+Each recommendation made by administrators has a weight: a number that tells how
+important a specific proposal is.  When the representative vote on a proposal
+matches the recommendation, their score on the proposal is set to +weight.
+Otherwise, it is set to -weight.
+
+Score decay parameters
+======================
+
+Memopol allows to set decay parameters so that older votes have a lower
+importance in the total representative score.  By default, those parameters are
+set to values that disable the score decay, so that each vote contributes
+identically to the total score no matter how old it is.
+
+The formula used to compute score is the following:
+
+.. image:: img/score_formula.png
+
+Where:
+
+* ``baseScore`` is the base score for the vote computed as explained above;
+* ``voteAge`` is the age of the vote in days;
+* ``decayNum`` and ``decayDenom`` define the decay rate;
+* ``exponent`` define the steepness of the decay.
+
+The corresponding parameters can be set from the Memopol administration
+interface (Memopol Settings > Settings); settings keys are ``SCORE_DECAY_NUM``,
+``SCORE_DECAY_DENOM``, ``SCORE_EXPONENT``. Additionnaly, the ``SCORE_DECIMALS``
+parameter sets how many decimal places are visible when scores are displayed.
+
+The default values for those settings disable score decay by setting
+``SCORE_DECAY_NUM`` to 0, ``SCORE_DECAY_DENOM`` and ``SCORE_EXPONENT`` to 1.
+
+If you want to use score decay, start by setting ``SCORE_DECAY_NUM`` to 1, and
+``SCORE_DECAY_DENOM`` to the number of days you want votes to matter.  The graph
+below shows how a score of 1.0 will decay with a 1-year decay (the X axis is in
+days).
+
+.. image:: img/score_1year.png
+
+Increasing ``SCORE_DECAY_DENOM`` will make votes matter longer.  Here is the
+same example but with a 10-year decay.
+
+.. image:: img/score_10years.png
+
+Increasing ``SCORE_EXPONENT`` instead will make the decay cutoff steeper.  Here
+is an example with a 1-year decay and the exponent set to 6.
+
+.. image:: img/score_exp6.png
+
+Increasing it dramatically will create a brutal cutoff; here is the same example
+with the exponent set to 1000:
+
+.. image:: img/score_exp1k.png

docs/setup_solr.rst

+Setup Solr with Memopol
+=======================
+
+Solr is used to perform search in the data. Currently, it is used only for
+reprensatative search autocomplete.
+
+This howto will be based on the current stable version of Debian (jessie).
+
+Installation on Debian Stable
+-----------------------------
+
+Solr is in the official repository of debian, you can install it launching::
+
+    # apt install solr-tomcat/stable
+    Package: solr-tomcat
+    Source: lucene-solr
+    Version: 3.6.2+dfsg-5
+    Installed-Size: 65,5 kB
+    Maintainer: Debian Java Maintainers <pkg-java-maintainers@lists.alioth.debian.org>
+    Depends: solr-common (= 3.6.2+dfsg-5), tomcat7
+    Conflicts: solr-jetty, solr-tomcat6
+    Homepage: http://lucene.apache.org
+    Section: java
+    Priority: optional
+    Download-Size: 8 598 B
+    APT-Sources: http://ftp.fr.debian.org/debian/ jessie/main amd64 Packages
+    Description: Enterprise search server based on Lucene3 - Tomcat integration
+     Solr is an open source enterprise search server based on the Lucene
+     Java search library, with XML/HTTP and JSON APIs, hit highlighting,
+     faceted search, caching, replication, and a web administration
+     interface. It runs in a Java servlet container such as Tomcat.
+     .
+     This package provides the Tomcat integration files for Solr.
+
+
+By default, the solr server is listen on localhost:8080. Memopol is configured
+to use this addess by default, in production. If you install a newer version of
+Solr (6.5.1 is the latest release), you should update the settings.py::
+
+    HAYSTACK_CONNECTIONS = {
+        'default': {
+            'ENGINE': 'haystack.backends.solr_backend.SolrEngine',
+            'URL': 'http://127.0.0.1:8080/solr',
+        },
+    }
+
+Configure Solr
+---------------
+
+You can use the default Solr configuration to use it, You just need to generate
+the schema.xml file and copy it in `/etc/solr/`. To generate the schema.xml
+file::
+
+    $ memopol build_solr_schema > schmema.xml
+
+    ## Copy the schema.xml file into /etc/solr/conf
+    $ sudo cp schema.xml /etc/solr/conf/
+
+    ## Restart tomcat
+    $ sudo /etc/init.d/tomcat7 restart
+
+Last step, you need to build the index by using::
+
+    $ memopol rebuild_index
+
+The solr is now setup and production ready.
+
+Populate data in Solr
+---------------------
+
+Django-haystack plugin offers two ways to populate data. The first way is by
+using a cron job to update the index, the other way is to use `Dango signals to
+update / delete datas <https://django-haystack.readthedocs.io/en/v2.6.0/signal_processors.html>`_.
+
+For now, Haystack is not configured to be used with Django signals. It is 
+necessary to add a cron job to update the index ::
+
+    $ memopol update_index
+
+`More informations about cron with Solr <http://django-haystack.readthedocs.io/en/v2.6.0/searchindex_api.html?highlight=cron#keeping-the-index-fresh>`_

docs/usage.rst

+User guide
+~~~~~~~~~~
+
+Authentication in the admin backend
+===================================
+
+As a content-editor, you should be able to connect to the administration
+interface with the credentials and link that your administrator sent you. If
+they haven't, please email them with a request and eventually a link to
+:doc:`administration`.
+
+Managing representative positions
+=================================
+
+Our dear representatives make promises to be elected. These can be submitted by
+visitors on the front-end so one of your tasks is to review them and publish
+them if they are appropriate.
+
+In "Positions -> Position -> Change" (url should be
+``/admin/positions/position/``), above the list table, click the "Published"
+select box and choose the "Published: No" option, then click "Search".
+Alternatively, you may bookmark
+``/admin/positions/position/?published__exact=0``.
+
+Click a "Position" and if it's appropriate then check the "Published" checkbox
+and click "Save". The position will now appear in the representative detail
+page.
+
+Managing vote recommendations
+=============================
+
+A recommendation represents the vote we want representatives to make on a
+proposal: representatives doing the "recommended" vote will have their score
+increased, others will have their score decreased. Some recommendations may be
+more important than others, you can change the number of score points a
+recommendation is worth by changing its "weight" (must be a positive integer).
+
+In "Votes -> Recommendations -> Change" (url should be
+``/admin/votes/recommendation/``), you can create, update or remove
+recommendations.
+
+Your change won't be visible on score as soon as you make it.
+
+Data updates
+============
+
+Data updates daily:
+
+- representatives details are updated daily,
+- dossiers are synchronised daily,
+- proposals are synchronised daily, when proposals are synchronised, they
+  become available to use in "Recommendations".
+- votes and scores are synchronised daily for proposals which have a
+  "Recommendation",
+
+This means that if a proposal arrives today in the database, you may add a
+recommendation for it. The next day, votes will be imported and scores will be
+updated as well.

memopol/.gitignore

-settings.py

memopol/settings.py.example

-"""
-Django settings for memopol project.
-
-For more information on this file, see
-https://docs.djangoproject.com/en/1.7/topics/settings/
-
-For the full list of settings and their values, see
-https://docs.djangoproject.com/en/1.7/ref/settings/
-"""
-
-# Build paths inside the project like this: os.path.join(BASE_DIR, ...)
-import os
-BASE_DIR = os.path.dirname(os.path.dirname(__file__))
-
-
-# Quick-start development settings - unsuitable for production
-# See https://docs.djangoproject.com/en/1.7/howto/deployment/checklist/
-
-# SECURITY WARNING: keep the secret key used in production secret!
-SECRET_KEY = 'zbzzs+8wkdnbo-l9x6+r38)$%h)!&22c^di$^6ap_+9oza#irr'
-
-# SECURITY WARNING: don't run with debug turned on in production!
-DEBUG = True
-
-TEMPLATE_DEBUG = True
-
-ALLOWED_HOSTS = []
-
-
-# Application definition
-
-INSTALLED_APPS = (
-    'django.contrib.admin',
-    'django.contrib.auth',
-    'django.contrib.contenttypes',
-    'django.contrib.sessions',
-    'django.contrib.messages',
-    'django.contrib.staticfiles',
-    # ---
-    'compressor',
-    'chronograph',
-    # ---
-    'core',
-    'representatives',
-    'memopol_representatives',
-)
-
-# App settings
-
-REPRESENTATIVES_COMPOTISTA_SERVER = 'http://pi2.octopuce.fr:8081'
-
-MIDDLEWARE_CLASSES = (
-    'django.contrib.sessions.middleware.SessionMiddleware',
-    'django.middleware.common.CommonMiddleware',
-    'django.middleware.csrf.CsrfViewMiddleware',
-    'django.contrib.auth.middleware.AuthenticationMiddleware',
-    'django.contrib.auth.middleware.SessionAuthenticationMiddleware',
-    'django.contrib.messages.middleware.MessageMiddleware',
-    'django.middleware.clickjacking.XFrameOptionsMiddleware',
-)
-
-ROOT_URLCONF = 'memopol.urls'
-
-WSGI_APPLICATION = 'memopol.wsgi.application'
-
-
-# Database
-# https://docs.djangoproject.com/en/1.7/ref/settings/#databases
-
-DATABASES = {
-    'sqlite': {
-        'ENGINE': 'django.db.backends.sqlite3',
-        'NAME': os.path.join(BASE_DIR, 'db.sqlite3'),
-    },
-    'default': {
-        'ENGINE': 'django.db.backends.postgresql_psycopg2',
-        'NAME': 'memopol_dev',
-        'USER': 'dj',
-        'PASSWORD': "test",
-        'HOST': 'localhost',
-        'PORT': '',
-    }
-}
-
-# Internationalization
-# https://docs.djangoproject.com/en/1.7/topics/i18n/
-
-LANGUAGE_CODE = 'en-us'
-
-TIME_ZONE = 'UTC'
-
-USE_I18N = True
-
-USE_L10N = True
-
-USE_TZ = True
-
-
-# Static files (CSS, JavaScript, Images)
-# https://docs.djangoproject.com/en/1.7/howto/static-files/
-
-STATIC_URL = '/static/'
-
-# HAML Templates
-# https://github.com/jessemiller/hamlpy
-
-TEMPLATE_DIRS = (
-    'core/templates',
-)
-
-TEMPLATE_LOADERS = (
-    'django.template.loaders.filesystem.Loader',
-    'django.template.loaders.app_directories.Loader',
-    'hamlpy.template.loaders.HamlPyFilesystemLoader',
-    'hamlpy.template.loaders.HamlPyAppDirectoriesLoader',
-)
-
-"""
-TEMPLATE_LOADERS = (
-    ('django.template.loaders.cached.Loader', (
-        'hamlpy.template.loaders.HamlPyFilesystemLoader',
-        'hamlpy.template.loaders.HamlPyAppDirectoriesLoader',
-    )),
-)
-"""
-
-# Static files finders
-
-STATIC_URL = '/static/'
-COMPRESS_ROOT = 'static/'
-
-STATICFILES_FINDERS = (
-    'django.contrib.staticfiles.finders.FileSystemFinder',
-    'django.contrib.staticfiles.finders.AppDirectoriesFinder',
-    # other finders..
-    'compressor.finders.CompressorFinder',
-)
-
-COMPRESS_PRECOMPILERS = (
-    # ('text/coffeescript', 'coffee --compile --stdio'),
-    ('text/less', 'lessc {infile} {outfile}'),
-    ('text/x-sass', 'sass {infile} {outfile}'),
-    ('text/x-scss', 'sass --scss {infile} {outfile}'),
-    # ('text/stylus', 'stylus < {infile} > {outfile}'),
-    # ('text/foobar', 'path.to.MyPrecompilerFilter'),
-)

memopol/urls.py

-from django.conf.urls import patterns, include, url
-from django.contrib import admin
-
-import core.views
-
-urlpatterns = patterns('',
-    # Examples:
-    # url(r'^$', 'memopol.views.home', name='home'),
-    url(r'^representatives/', include('memopol_representatives.urls', namespace='representatives')),
-    url(r'^$', core.views.HomeView.as_view(), name='index'),
-    url(r'^admin/', include(admin.site.urls)),
-)

memopol/utils.py

-import sys
-
-def progress_bar(n, total):
-    progress = float(n) / total
-    sys.stdout.write("\r[{0:30s}] ({1}/{2}) {3}%".format('#' * int(progress * 30), n, total, int(progress * 100)))

memopol_representatives/admin.py

-from django.contrib import admin

memopol_representatives/models.py

-from django.db import models

memopol_representatives/templates/memopol_representatives/list.haml

-- extends "base.html"
-
-- block content
-  - include 'memopol_representatives/search.html'
-
-  %table
-    - for representative in representatives
-      %tr
-        - include 'memopol_representatives/representative_block.html'
-
-  .pagination
-    %span.step-links
-      - if representatives.has_previous
-        %a{'href': '?={queries.urlencode}&page=={representatives.previous_page_number}'} previous
-
-      %span.current
-        Page ={representatives.number} of ={representatives.paginator.num_pages}
-
-      - if representatives.has_next
-        %a{'href': '?={queries.urlencode}&page=={representatives.next_page_number}'} next

memopol_representatives/templates/memopol_representatives/representative_block.haml

-%td<
-  %a{'href': "{% url 'representatives.detail' ={representative.id} %}"} 
-    %img{'src':'={representative.photo}'}/
-
-%td<
-  %a{'href': "{% url 'representatives.detail' ={representative.id} %}"} 
-    ={representative.full_name} [={representative.country.code}]
-
-%td<
-  - for mandate in representative.mandate_set.all
-    ={mandate.group.name}
-    %br/a
-

memopol_representatives/templates/memopol_representatives/representative_block.html

-<td>
-  <a href="{% url 'representatives:view' representative.id %}">
-    <img src="{{ representative.photo }}" />
-  </a>
-</td>
-<td>
-  <a href="{% url 'representatives:view' representative.id %}">
-    {{ representative.full_name }}&nbsp;[{{ representative.country.code }}]
-  </a>
-</td>
-

memopol_representatives/templates/memopol_representatives/search.html

-<form action="{% url 'representatives:index' %}" method="get">
-  {% csrf_token %}
-  <label for="search">Search : </label>
-  <input id="search" type="text" name="search">
-  <input type="submit" value="Go">
-</form>

memopol_representatives/templates/memopol_representatives/view.html

-{% extends 'base.html' %}
-
-{% block content %}
-
-<a href="{% url 'representatives:index' %}">Back</a>
-
-<p style="float: left">
-  <img src="{{ representative.photo }}">
-</p>
-
-<h1>{{ representative.full_name }}</h1>
-
-<p>
-  {{ representative.country.name }} {{ representative.gender }} <br>
-  Born in {{ representative.birth_place }} the {{ representative.birth_date }} <br>  
-</p>
-
-<h2 style="clear: both">Mandates</h2>
-{% for mandate in representative.mandate_set.all %}
-<div class="mandate">
-  <h3>
-    {{ mandate.group.name }}
-    <small>
-      {{ mandate.role }}
-    </small>
-  </h3>
-  <p>
-    {{ mandate.begin_date }} to {{ mandate.end_date }} <br>
-    <strong>{{ mandate.group.kind }}</strong> : <em>{{ mandate.group.name }} ({{ mandate.group.abbreviation }})</em> <br>
-    Constituency : {{ mandate.constituency.name }} <br>
-  </p>
-</div>
-<hr>
-{% endfor %}
-
-{% endblock %}

memopol_representatives/tests.py

-from django.test import TestCase
-
-# Create your tests here.