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.

legislature/admin.py

-from django.contrib import admin

legislature/management/commands/fix_mandates_active.py

-import datetime
-from django.core.management.base import BaseCommand
-from representatives.models import Mandate
-from django.db import transaction
-
-
-class Command(BaseCommand):
-
-    @transaction.atomic
-    def handle(self, *args, **options):
-        date = datetime.datetime.now().date()
-        mandates = Mandate.objects.all()
-        n = len(mandates)
-        for i, mandate in enumerate(mandates):
-            mandate.active = mandate.end_date > date
-            mandate.save()
-            print("%s/%s\r" % (i, n)),

legislature/management/commands/legislature_updates_models.py

-# import datetime
-from django.core.management.base import BaseCommand
-from representatives import models
-from legislature.models import Representative, Mandate
-
-from django.db import transaction
-
-
-class Command(BaseCommand):
-
-    @transaction.atomic
-    def handle(self, *args, **options):
-        # Representatives
-        print('Representatives')
-        n = models.Representative.objects.all().count()
-        for i, representative in enumerate(models.Representative.objects.all()):
-            legislature_representative = Representative(representative_ptr=representative)
-            legislature_representative.__dict__.update(representative.__dict__)
-            legislature_representative.update_country()
-            legislature_representative.save()
-            print("%s/%s\r" % (i, n)),
-
-        print('Mandates')
-        for i, representative in enumerate(Representative.objects.all()):
-            legislature_mandates = []
-            for mandate in representative.mandate_set.all():
-                legislature_mandate = Mandate(mandate_ptr=mandate)
-                legislature_mandate.__dict__.update(mandate.__dict__)
-                legislature_mandate.update_active()
-                legislature_mandate.save()
-                legislature_mandates.append(legislature_mandate)
-            representative.update_active()
-            representative.save()
-            print("%s/%s\r" % (i, n)),

legislature/migrations/0001_initial.py

-# -*- coding: utf-8 -*-
-from __future__ import unicode_literals
-
-from django.db import models, migrations
-
-
-class Migration(migrations.Migration):
-
-    dependencies = [
-        ('representatives', '0004_representative_country'),
-    ]
-
-    operations = [
-        migrations.CreateModel(
-            name='Constituency',
-            fields=[
-                ('constituency_ptr', models.OneToOneField(parent_link=True, auto_created=True, primary_key=True, serialize=False, to='representatives.Constituency')),
-            ],
-            options={
-            },
-            bases=('representatives.constituency',),
-        ),
-        migrations.CreateModel(
-            name='Group',
-            fields=[
-                ('group_ptr', models.OneToOneField(parent_link=True, auto_created=True, primary_key=True, serialize=False, to='representatives.Group')),
-            ],
-            options={
-            },
-            bases=('representatives.group',),
-        ),
-        migrations.CreateModel(
-            name='Mandate',
-            fields=[
-                ('mandate_ptr', models.OneToOneField(parent_link=True, auto_created=True, primary_key=True, serialize=False, to='representatives.Mandate')),
-            ],
-            options={
-            },
-            bases=('representatives.mandate',),
-        ),
-        migrations.CreateModel(
-            name='Representative',
-            fields=[
-                ('representative_ptr', models.OneToOneField(parent_link=True, auto_created=True, primary_key=True, serialize=False, to='representatives.Representative')),
-            ],
-            options={
-            },
-            bases=('representatives.representative',),
-        ),
-    ]

legislature/models.py

-from django.db import models
-import representatives
-import datetime
-
-
-class Representative(representatives.models.Representative):
-    active = models.BooleanField(default=False)
-    country = models.ForeignKey(representatives.models.Country, null=True)
-
-    def active_mandates(self):
-        return self.mandate_set.filter(active=True)
-
-    def former_mandates(self):
-        return self.mandate_set.filter(active=False)
-
-    def current_group(self):
-        return self.mandate_set.get(
-            active=True,
-            group__kind='group'
-        )
-
-    def update_active(self):
-        # If a representative has at least one active manadate
-        self.active = False
-        for mandate in self.mandate_set.all():
-            if mandate.active:
-                self.active = True
-                continue
-
-        self.save()
-
-    def update_country(self):
-        # Create a country if it does not exist
-        # The representative's country is the one associated
-        # with the last 'country' mandate
-        country_mandate = self.mandate_set.filter(
-            group__kind='country'
-        ).order_by('-begin_date')[0:1].get()
-
-        country, created = representatives.models.Country.objects.get_or_create(
-            name=country_mandate.group.name,
-            code=country_mandate.group.abbreviation
-        )
-        self.country = country
-        self.save()
-
-
-class Mandate(representatives.models.Mandate):
-
-    def update_active(self):
-        date = datetime.datetime.now().date()
-        self.active = self.end_date > date
-        self.save()

legislature/templates/legislature/group_list.haml

-- extends 'base.html'
-
-- block content
-  - for group in groups
-    {{ group.name }} 
-    %br

legislature/templates/legislature/representative_block.haml

-- load by_mandate_url
-
-%td
-  %a{'href': "{% url 'legislature:representative_view_by_name' representative.full_name %}"} 
-    %img{'src': '={representative.photo}', 'width': '80'}/
-
-%td
-  %a{'href': "{% url 'legislature:representative_view_by_name' representative.full_name %}"} 
-    ={representative.full_name}
-
-%td
-  %a{'href': "{% url 'legislature:representatives_by_mandate' mandate_kind='country' search=representative.country.code %}"}
-    ={representative.country.name}
-
-%td
-  %a{'href': "{{ representative.current_group|by_mandate_url }}"}
-    ={representative.current_group.group.abbreviation}

legislature/templates/legislature/representative_view.html

-{% extends 'base.html' %}
-{% load by_mandate_url %}
-
-{% block content %}
-
-<p style="float: left">
-  <img src="{{ representative.photo }}">
-</p>
-
-<h1>{{ representative.full_name }}</h1>
-<p>
-  <strong>
-    <a href="{{ representative.current_group|by_mandate_url }}">
-      {{ representative.current_group.role }} of {{ representative.current_group.group.name }}
-    </a>
-  </strong>
-</p>
-
-<p>Born in {{ representative.birth_place }} the {{ representative.birth_date }} ({{ representative.get_gender_display }})</p>
-<p>{{ representative.country.name }}</p>
-
-<h2 style="clear: both">Mandates</h2>
-{% for mandate in representative.active_mandates %}
-<div class="mandate">
-  <h3>
-    {{ mandate.group.name }}
-    <small>
-      {{ mandate.role }}
-    </small>
-  </h3>
-  <p>
-    {{ mandate.begin_date }} to {{ mandate.end_date }} <br>
-    <a href="{{ mandate|by_mandate_url }}">
-      <strong>{{ mandate.group.kind }}</strong> : <em>{{ mandate.group.name }} ({{ mandate.group.abbreviation }})</em> 
-    </a>
-    <br>
-    Constituency : {{ mandate.constituency.name }} <br>
-  </p>
-</div>
-<hr>
-{% endfor %}
-
-<h2>Former mandates</h2>
-{% for mandate in representative.former_mandates %}
-<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 %}

legislature/templates/legislature/representatives_list.haml

-- extends "base.html"
-
-- block content
-
-  - include 'legislature/search.html'
-
-  %p
-    Number of representatives: {{ representative_num  }}
-
-  %table
-    - for representative in representatives
-      %tr
-        - include 'legislature/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

legislature/templates/legislature/search.html

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

legislature/templatetags/by_mandate_url.py

-from django import template
-from django.core.urlresolvers import reverse
-
-register = template.Library()
-
-
-@register.filter
-def by_mandate_url(mandate):
-    kwargs = {'mandate_kind': mandate.group.kind}
-
-    if mandate.group.abbreviation:
-        kwargs['search'] = mandate.group.abbreviation
-    else:
-        kwargs['search'] = mandate.group.name
-
-    return reverse(
-        'legislature:representatives_by_mandate',
-        kwargs=kwargs
-    )