feat(doc): démarrage de la documentation

.gitignore

@@ -40,3 +40,5 @@ var/
 
 # Asset builds hidden in developp branch
 gvot/static/
+styleguide/index.html                                                           
+docs/build/

Makefile

@@ -60,7 +60,7 @@ endif
 
 # Définition des cibles -------------------------------------------------------
 
-.PHONY: clean-pyc clean-build clean-static clear-venv help check check-config
+.PHONY: clean-pyc clean-build clean-static clear-venv help check check-config docs clean-docs
 .DEFAULT_GOAL := help
 
 # Commentaire d'une cible : #-> interne ##-> aide production+dev ###-> aide dev
@@ -160,3 +160,11 @@ fix-lint: ### corrige la syntaxe et ordonne les imports python
 ifdef USE_BLACK
 	$(PYTHON) -m black gvot
 endif
+
+## Cibles pour la documentation
+
+docs: ## construit la documentation
+	$(MAKE) -C docs/ html SPHINXBUILD=../$(VENV_DIR)/bin/sphinx-build
+
+clean-docs:  ## supprime la documentation (docs/build)
+	$(MAKE) -C docs/ clean SPHINXBUILD=../$(VENV_DIR)/bin/sphinx-build

docs/Makefile

@@ -0,0 +1,22 @@
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees
+
+.PHONY: help clean html linkcheck
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  linkcheck  to check all external links for integrity"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(ALLSPHINXOPTS)
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)/linkcheck" $(ALLSPHINXOPTS)

docs/source/_static/css/custom.css

@@ -0,0 +1,4 @@
+/* Hide autoclass name; we only want docstrings */
+.rst-content dl.class > dt {
+  display: none;
+}

docs/source/administration/index.rst

@@ -0,0 +1,56 @@
+Guide d'administration
+**********************
+
+Cette documentation couvre l'administration de l'application par les
+administrateurs.
+
+.. toctree::
+   :maxdepth: 1
+
+
+Créer un compte administrateur
+==============================
+
+Il est conseillé de créer un compte dédié à l'administration, qui doit être
+utilisé avec la plus grande parcimonie.
+
+Sur le serveur de production :
+
+::
+
+    $ ./venv/bin/python manage.py createsuperuser
+    Adresse mail: admin@example.org
+    Password: •••••••••••••
+    Password (again): •••••••••••••
+    Superuser created successfully.
+
+
+Utilisation du compte administrateur
+====================================
+
+L'accès à l'administration se fait à l'emplacement `/admin`.
+
+Une fois connecté avec le compte administrateur, le CMS Wagtail est utilisable
+comme `indiqué dans sa documentation
+<https://docs.wagtail.io/en/v2.7/editor_manual/index.html>`_.
+
+Spécificités CMS de GvoT par rapport à Wagtail
+==============================================
+
+Gestion des scrutins dans GvoT
+==============================
+
+Ajout d'un index des scrutins
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Ajout d'un scrutin
+^^^^^^^^^^^^^^^^^^
+
+Ajout des pouvoirs
+^^^^^^^^^^^^^^^^^^
+
+Importation des pouvoirs
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Expédition d'un mailling
+^^^^^^^^^^^^^^^^^^^^^^^^

docs/source/conf.py

@@ -0,0 +1,118 @@
+"""
+Documentation build's configuration for GvoT.
+
+This file does only contain a selection of the most common options. For a
+full list see the documentation:
+http://www.sphinx-doc.org/en/master/config
+"""
+import os
+import sys
+import django
+
+sys.path.insert(0, os.path.abspath('../..'))
+from gvot.settings import DJANGO_SETTINGS_MODULE
+
+os.environ.setdefault('DJANGO_SETTINGS_MODULE', DJANGO_SETTINGS_MODULE)
+django.setup()
+
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath('../../'))
+
+# sys.setrecursionlimit(1500)  # default is usually about 1000
+
+os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'gvot.settings.test')
+
+
+# -- Project information -----------------------------------------------------
+
+from gvot import __version__  # noqa: E402
+
+project = "GvoT"
+author = "Cliss XXI"
+copyright = "2020, Cliss XXI, released under the GNU AGPLv3+ License"
+
+# 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 = __version__
+# The full version, including alpha/beta/rc tags.
+release = version
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# 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']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+source_suffix = ['.rst']
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = 'fr'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'sphinx_rtd_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+html_theme_options = {'logo_only': True}
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+html_title = "Documentation de GvoT"
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+html_short_title = "Documentation"
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+html_logo = '../../assets/img/logo.svg'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If true, the reST sources are included in the HTML build as _sources/name.
+html_copy_source = False
+
+# If true, links to the reST sources are added to the pages.
+html_show_sourcelink = False
+
+# Tweak rendering
+def setup(app):
+    app.add_css_file('css/custom.css')

docs/source/considerations.rst

@@ -0,0 +1,167 @@
+Considérations générales sur le vote en ligne
+*********************************************
+
+Il nous semble important de préciser ici que **GvoT** est une solution de vote
+en ligne et que, à ce titre, il faut être conscient des limites d'un tel outil.
+
+A fortiori, **GvoT** est conçu pour des besoins typiques d'un contexte de prises
+de décisions formelles. Le caractère d'urgence et de force majeur que nous
+impose la crise du COVID19 pourrait sembler justifier quelques libertés prises
+avec la forme d'un scrutin. Après tout, pourrait on se dire, « *papier ou
+électronique, quelle différence cela fait pour les participants au vote ?* »
+
+Néanmoins il se trouve qu'un scrutin électronique n'a pas les propriétés d'un
+scrutin à bulletin secret dans une urne transparente et il faut en être
+conscient. À ce titre, il n'offre pas du tout les mêmes garanties (voir par
+exemple l’`excellente synthèse
+<https://wiki.april.org/w/Discussion_vote_%C3%A9lectronique>`_ de
+l’`April <https://april.org/>`_ sur le sujet). Et le fait que **GvoT** soit
+un logiciel libre ne dédouanne pas de tous les risques de manipulation.
+
+Difficultés techniques
+======================
+
+Compromis contrôlabilité/traçabilité
+------------------------------------
+
+La nature d'un scrutin en ligne est différente de celui impliquant une urne
+physique. En particulier, il n'existe aucune méthode connue permettant à la
+fois :
+
+* Le **contrôle** du scrutin par les participant⋅e⋅s (vérifier que ce tous les
+  votes sont pris en compte et seulement eux).
+
+* La **non-traçabilité** du scrutin (préservation de l'anonymat des
+  participant⋅e⋅s).
+
+En l'état de l'art, cette aporie est un problème théorique ouvert qui ne
+possède pas à notre connaissance de solution technologique (y compris à base de
+chiffrement et/ou autre blockchain).
+
+Le chiffrement n'est pas une solution, notamment car il ne protège pas contre
+le bourrage d'urnes. Contrôler un scrutin ne se limite pas à ce que je contrôle
+que mon expression est prise en compte. Contrôler un scrutin implique aussi de
+contrôler que l'expression de chacun et seulement elle est prise en compte.
+
+La conséquence de ça, est que, en cas de réclamation, la seule option possible
+d'établir les faits est d'ouvrir le scrutin afin que **chacun** puisse
+**contrôler** que **tous les votes** sont pris en compte et **seulement eux**.
+Cela s'apparenterait à « rejouer » le scrutin, à main levée.
+
+L'ouverture du scrutin doit donc pouvoir être demandé à l'organisateur.
+L'intégralité des personnes devraient alors recevoir un accès à l'intégralité
+des données propres au scrutin concerné. 
+
+Dépendance à la technologie email
+---------------------------------
+
+Pour des raisons de rapidité d'organisation et d'interopérabilité, l'envoi des
+pouvoirs se fera par courriel.
+
+Un hébergeur de **GvoT** devrait s'engager à une obligation de moyen pour
+permettre au mieux la délivrance des pouvoirs aux adresses destinataires par
+courriel.
+
+Néanmoins du fait de la nature décentralisée des protocoles de courriels et de
+la difficulté majeure de vérifier des identités en ligne :
+
+* Les hébergeurs ne peuvent garantir que les courriels seront **présentés** aux
+  personnes jugées légitimes. Hors de notre périmètre, on ne contrôle pas que
+  le courriel atterrit dans le dossier des courriels à lire en urgence.
+
+* Les hébergeurs ne peuvent garantir que les courriels envoyés **seront lus**
+  par les personnes jugées légitimes. Hors de notre périmètre on ne contrôle
+  pas que les personnes relèvent la bonne boite.
+
+* Les hébergeurs ne peuvent garantir que les courriels envoyés seront lus **par
+  les seules personnes** jugées légitimes. Rien n'empêche les fuites
+  d'information et donc la fuite des pouvoirs.
+
+Conseils aux usagers
+====================
+
+La coopérative Cliss XXI reconnaît la nature particulièrement sensible des
+données et des résultats d'un scrutin d'assemblée générale, de modification de
+statut ou d'un règlement intérieur.
+
+À ce titre elle insiste sur ce qui fait la bonne tenue d'un scrutin en insistant
+particulièrement au travers 3 axes : ouverture, transparence et neutralité.
+
+`<Ouverture>`_ car le logiciel est libre. `<Transparence>`_ des pratiques et
+reconnaissance des limitations existantes. `<Neutralité>`_ par déontologie,
+en tant que prestataire technique d'hébergement tel que définit par la
+loi sur la confiance en l'économie numérique (LCEN).
+
+Ouverture
+---------
+
+**GvoT** est un logiciel libre : sous licence `GNU Affero GPL
+<https://forge.cliss21.org/cliss21/gvot/src/branch/master/LICENSE>`_. Une
+disposition spéciale de cette licence est que tout utilisateur du logiciel est
+en droit d'obtenir une copie de son code source avec les permissions usuelles
+du logiciel libre (droits d'usage, d'étude, de modification, de redistribution).
+
+Le code du logiciel est disponible sur la `forge de Cliss XXI
+<https://forge.cliss21.org/cliss21/gvot>`_ .
+
+Un hébergeur de **GvoT** devrait s’engager sur l'honneur que le code utilisé
+pour le vote est celui publié et librement auditable par ailleurs.
+
+Un hébergeur de **GvoT** devrait s’engager sur l’honneur que l'accès aux
+données du vote n'est accessible à aucune autre application que la présente
+plateforme hébergée ainsi que le socle technique qui la porte.
+
+La procédure de vote et d'administration du vote sur le site web devrait être
+protégée par le chiffrement **TLS** en vigueur au moment du vote (TLS version
+1.2 ou 1.3 au moment du COVID19). Il s’agit d’un standard international
+recommandé et conforme aux préconisations de l'ANSSI.
+
+Transparence
+------------
+
+Un hébergeur de **GvoT** devrait reconnaître les limites technologiques et
+déontologiques qui affectent le vote en ligne pour un scrutin à bulletin
+secret.
+
+Un hébergeur de **GvoT** devrait s’engager sur l'honneur que les données du
+scrutin soient recueillies dans le seul but décrit en introduction du scrutin.
+En conséquence ces données ainsi que celles recueillies dans le cadre du vote
+ne seraient pas utilisées à d’autres fins ni transmises à un tiers.
+
+Un hébergeur de **GvoT** devrait s’engager sur l'honneur en accord avec
+l'organisateur, que ces données **soient détruites** une fois le scrutin passé,
+et dans tous les cas au plus tard un certain nombre jours après la fin de la
+tenue du scrutin.
+
+Dans tous les cas, les participant⋅e⋅s disposent d’un droit d’accès, de
+modification, de rectification et de suppression des données les concernant
+(loi « Informatique et Liberté » du 6 janvier 1978).
+
+Un hébergeur de **GvoT** devrait s’engager sur l’honneur de ne pas cacher la
+détection d'un comportement anormal s'il était détecté (piratage, fuite
+accidentelle d'informations, etc.).
+
+Neutralité
+----------
+
+Un hébergeur de **GvoT** devrait s'engager à une obligation de moyen pour
+permettre la tenu du scrutin dans les meilleurs conditions. 
+
+Cela implique, de façon non exhaustive à :
+
+* suivre l'expédition des courriels d'annonce,
+* veiller à la disponibilité de la plateforme aux heures ouvrées pendant la
+  durée du scrutin,
+* répondre aux demandes d'assistance des utilisateurs.
+
+Un moyen d'accéder à l'assistance devrait être précisée sur la plateforme de
+vote ainsi que dans chaque courriel expédié aux participant⋅e⋅s.
+
+Un hébergeur de **GvoT** devrait s'engager sur l'honneur à ne procéder à aucune
+intervention qui soit de nature à biaiser l'issue du scrutin. Les éventuelles
+interventions se feront uniquement sous la forme d'une assistance avec une
+éventuelle intervention qui sera strictement proportionné à la demande de la
+personne assistée dans le vote.
+
+En cas d'intervention impliquant les données du scrutin, un journal des
+interventions devrait être tenu avec soin.

docs/source/contribuer.rst

@@ -0,0 +1,102 @@
+Contribuer
+**********
+
+Ceci est le guide de contribution pour **GvoT**, qui est basé sur Python
+et Django. Si vous êtes habité au développement de logiciels libres et démarrer
+rapidement, vous pouvez directement regarder la `liste des bugs et demandes de
+fonctionnalités <https://forge.cliss21.org/cliss21/gvot/issues>`_.
+
+Autrement cette section est faite pour vous.
+
+Ressources
+==========
+
+* Dépôt et suivi de bugs : https://forge.cliss21.org/cliss21/gvot
+* Forum : non défini
+* Messagerie instantanée : non définie
+* Licence : `AGPLv3+ <https://forge.cliss21.org/cliss21/gvot/src/branch/master/LICENSE>`_
+* Contact : :doc:`voir l'équipe <equipe>`
+* Pré-requis à la contribution : `Tests d'intégrations`_, `Analyse statique`_
+
+Organisation
+============
+
+L':doc:`équipe de développement <equipe>` de **GvoT** est organisée
+horizontalement.
+
+Les contributions sont discutées puis intégrées à l'issue d'un consensus.
+
+Il est d'usage que les contributions ne soient pas intégrées par la personne
+qui les soumet, mais par une tierce personne qui vérifie la qualité et la
+cohérence de la contribution.
+
+Pour démarrer avec **GvoT**
+===========================
+
+Suivre `README.md
+<https://forge.cliss21.org/cliss21/gvot/src/branch/master/README.md>`_
+pour obtenir une instance de test et construire les `assets`.
+
+
+Organisation du dépôt
+=====================
+
+* ``docs/`` contient la documentation.
+* ``asset/`` contient les sources du `frontend`.
+* ``gvot/`` contient le projet Django.
+* ``gvot/settings/`` contient les réglages du projet Django.
+* ``gvot/templates/`` contient les gabarits html du projet Django.
+* ``gvot/<app>/`` contient l'application `<app>` du projet Django.
+* ``gvot/<app>/tests`` contient les tests de l'application `<app>`.
+* etc.
+
+Tests d'intégrations
+====================
+
+S'agissant du `backend`, les tests unitaires sont bienvenus. Les tests
+d'intégration sont obligatoires.
+
+Toute contribution modifiant ou ajoutant un comportement au `backend` est a
+priori attendue avec un test qui vérifie le comportement attendu, et
+l'exécution suivante doit être un succès :
+
+::
+
+    make test
+
+Un résumé de la couverture de test sera annoncé :
+
+* Une contribution ne devra pas, a priori, réduire la couverture de tests.
+* Une contribution ne devra pas, a priori, comporter de code non couvert.
+* Le code mort résultant de potentiel traitement d'erreur est toléré.
+
+
+Analyse statique
+================
+
+Toute contribution est priée de valider l'analyse statique du code.
+
+`Backend`
+^^^^^^^^^
+
+S'agissant du `backend`, l'exécution suivante doit être un succès :
+
+::
+
+    make lint
+
+Par ailleurs le code Python d'une contribution est attendu après un passage de
+`Black <https://black.readthedocs.io/en/stable/>`_ pour formatter uniformément
+son style. Black peut être ininstallable du fait de la version de Python de
+votre système (Python < 3.6).  Dans ce cas précis il se peut que vous deviez
+l'installer et l'utiliser séparément.
+
+`Frontend`
+^^^^^^^^^^
+
+S'agissant du `frontend`, l'exécution suivante doit être un succès :
+
+::
+
+    npm run lint
+

docs/source/equipe.rst

@@ -0,0 +1,22 @@
+L'équipe
+********
+
+La communauté **GvoT** est ouverte aux membres qui souhaitent s'investir. Si
+cela vous intéresse vous pouvez vous manifester sur `l'adresse de contact de
+Cliss XXI <mailto:contact@cliss21.com>`_.
+
+Vous pouvez aussi directement vous impliquer dans le développement sur la
+`forge du projet <https://forge.cliss21.org/cliss21/gvot>`_. Voyez pour cela la
+section « :doc:`contribuer` ».
+
+Contact
+=======
+
+Vous povez contacter la SCIC sur `l'adresse de contact de Cliss XXI
+<mailto:contact@cliss21.com>`_.
+
+Développement
+=============
+
+Le développement logiciel est assuré par François Poulain de `Cliss XXI
+<https://cliss21.com>`_.

docs/source/heberger.rst

@@ -0,0 +1,10 @@
+Héberger **GvoT**
+*****************
+
+L'hébergement d'une instance de **GvoT** nécessite un serveur
+d'application Python. **GvoT** est maintenu de sorte à être facilement
+hébergé sur un serveur Debian GNU/Linux version 10 « Buster ».
+
+Les détails se trouvent dans le fichier `README.md
+<https://forge.cliss21.org/cliss21/gvot/src/branch/master/README.md>`_ à
+la `racine du dépôt <https://forge.cliss21.org/cliss21/gvot/>`_.

docs/source/index.rst

@@ -0,0 +1,19 @@
+Documentation de GvoT
+*********************
+
+**GvoT** est une application Web visant à permettre le vote en ligne à
+large échelle dans les organisations.
+
+Table des matières
+------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   presentation
+   utilisation
+   administration/index
+   considerations
+   equipe
+   heberger
+   contribuer

docs/source/presentation.rst

@@ -0,0 +1,75 @@
+Présentation
+************
+
+**GvoT** est une application Web visant à permettre le vote en ligne à
+large échelle dans les organisation.
+
+**GvoT** est né d’un besoin pendant la crise du COVID19 : permettre
+l'organisation de votes d'assemblées générales en ligne pour les collectifs
+démocratiques d'envergure régionale voire nationale.
+
+**GvoT** est né d’une coopération entre acteurs qui ont convergé quant
+aux besoins de leurs membres et qui ont décidé d’investir du temps pour que cet
+outil aboutisse au-delà de leurs propres besoins et qu’il serve, d’une manière
+plus générale, les associations en France.
+
+
+Fonctionnalités
+===============
+
+* Permet de publier les contenus web usuels (pages, images, documents, ...) via
+  un gestionnaire de contenu (`Wagtail <https://wagtail.io>`_).
+* Permet de publier des questionnaires en ligne, les « scrutins ».
+* Permet un vote à bulletin secret, :doc:`avec les limites que cela implique
+  <considerations>`.
+* Permet de gérer tout type de question dans l'interface (texte libre, choix
+  unique, choix multiples, etc.).
+* Permet de gérer les « pouvoirs » donnant accès au scrutin. L'interface est
+  conçue pour gérer des milliers de pouvoirs.
+* Permet l'importation des pouvoirs depuis un fichier tableur, avec
+  dédoublonnage et validateur intégré.
+* Permet la transmission des pouvoirs par courriel avec une prévisualisation
+  des courriels envoyés.
+* Permet de pondérer les pouvoirs pour les organisations de type fédération qui
+  le nécessitent.
+* Permet au participant de revenir vérifier et corriger son choix.
+* Notifie le participant de son vote.
+* Permet de notifier par courriel un tiers à chaque vote.
+
+Ne sont pas encore implantés dans le logiciel :
+
+* Gestion des collèges.
+* Personnalisation des gabarits de courriels dans l'interface.
+
+Pourquoi **GvoT** ?
+===================
+
+Habituellement, les rencontres physiques sont des moments privilégiées de la
+vie associative et peu d'organisations ont recours au vote en ligne. Seule
+éventuellement des grosses organisations d'envergures nationales y recourent
+pour augmenter leur participation et atteindre un quorum.
+
+Néanmoins la crise du COVID19 fait émerger le besoin de valider en urgence
+et à distance des décisions d'assemblées, pour faire face par exemple à des
+obligations statutaires ou des contraintes budgétaires.
+
+Pour répondre à ce besoin, Cliss XXI a choisi de développer et de mettre à
+disposition un outil dédié : **GvoT**. Cet outil est destiné principalement
+aux moyennes et grosses associations. Il est cependant libre et peut donc
+être déployé partout où le besoin s'en ferait sentir.
+
+Qui est à l'origine de **GvoT** ?
+=================================
+
+`Cliss XXI <https://www.cliss21.com>`_ est une SCIC (société coopérative
+d’intérêt collectif). Son objectif d’utilité sociale consiste à accompagner
+le développement technologique des PME-PMI, des collectivités territoriales et
+des associations de la région, en aidant leurs personnels (utilisateurs et
+informaticiens) à comprendre quels usages ils peuvent faire des logiciels libres,
+et à développer avec eux des solutions concrètes.
+
+Il nous semble important de préciser ici que **GvoT** est né d’une demande de
+la Ligue de l'Enseignement du Pas de Calais, et s'enrichie par ailleurs des
+pratiques connues des organisations du logiciel libre, notamment celles de
+l’`April <https://april.org/>`_ (voir par exemple leur `excellente synthèse
+<https://wiki.april.org/w/Discussion_vote_%C3%A9lectronique>`_ sur le sujet).

docs/source/utilisation.rst

@@ -0,0 +1,61 @@
+Guide d'utilisation
+*******************
+
+Cette documentation couvre l'utilisation de **GvoT** par le public.
+
+Accès à un scrutin
+==================
+
+Accéder à un scrutin est normalement impossible pour quelqu'un qui ne possède
+pas de « pouvoir ».
+
+En tant que participant à un scrutin vous avez dû recevoir une invitation
+par courriel. Cette invitation devrait notamment comporter un lien qui
+ressemble à :
+
+::
+
+    https://je.vote.pour.mon.asso/d3b64908-f7cf-4ba5-ba2f-828610093afe/
+
+Ce lien est un secret non devinable, idéalement connu de vous seul. Il a la
+même valeur qu'un mot de passe.
+
+Il suffit en général de cliquer sur le lien pour accéder au scrutin dans votre
+navigateur web. Si cliquer ne fonctionne pas ; vous devez `copier/coller
+<https://debian-facile.org/projets/lescahiersdudebutant/les_cahiers_du_debutant.html#copier-coller-une-selection>`_
+le lien entier (et sans erreur) dans la `barre d'adresse
+<https://support.mozilla.org/fr/kb/autocompletion-barre-adresse-firefox#w_autocomplaetion-de-laourl>`_
+de votre navigateur.
+
+Alors vous devriez avoir accès au scrutin qui se compose d'un texte préambule
+suivi d'un questionnaire à envoyer.
+
+Voter
+=====
+
+Pour voter il suffit d'accéder au scrutin et de répondre au questionnaire.
+Selon le questionnaire, les réponses peuvent être contraintes. Il vous faudra
+donc veiller à bien valider le formulaire, sans quoi il vous sera représenté
+pour correction. Si vous ne poursuiviez pas cette étape, votre vote ne saurait
+être pris en compte.
+
+Une fois votre vote enregistré une page de confirmation vous sera présenté et
+un courriel de confirmation vous sera expédié.
+
+Corriger son vote
+=================
+
+Pour contrôler et corriger son vote il suffit d'accéder au scrutin et de lire
+et/ou re-répondre au questionnaire.
+
+Une fois votre éventuelle modification enregistrée, une page de confirmation
+vous sera présenté et un courriel de confirmation vous sera expédié.
+
+Transférer son vote
+===================
+
+Pour transférer son vote il suffit de transférer le lien secret qui vous a été
+remis par courriel. Quiconque possède ce lien peut voter.
+
+Une fois un éventuel vote enregistré, un courriel de confirmation vous sera
+tout de même expédié à votre adresse courriel initiale.

gvot/settings/base.py

@@ -262,3 +262,8 @@ WAGTAIL_ENABLE_UPDATE_CHECK = False
 # ------------------------------------------------------------------------------
 # APPLICATION AND 3RD PARTY LIBRARY SETTINGS
 # ------------------------------------------------------------------------------
+
+# DOCS
+# ------------------------------------------------------------------------------
+# https://django-docs.readthedocs.io/en/latest/
+DOCS_ROOT = base_dir('docs/build/html')

gvot/settings/gvot.py

@@ -4,12 +4,15 @@ from . import env
 Django specific settings for GvoT project.
 """
 
+# WAGTAIL
+# ------------------------------------------------------------------------------
 THIRD_PARTY_APPS = [
     'wagtail.contrib.modeladmin',
     'wagtail.contrib.routable_page',
     'wagtailmenus',
     'widget_tweaks',
     'mailer',
+    'docs',
 ]
 
 WAGTAILMENUS_FLAT_MENUS_HANDLE_CHOICES = (('footer', 'Menu de pied de page'),)
@@ -19,4 +22,6 @@ WAGTAILEMBEDS_FINDERS = [
     {'class': 'wagtailembedpeertube.finders'},
 ]
 
+# MISC
+# ------------------------------------------------------------------------------
 ASSISTANCE = env('ASSISTANCE', default='assistance@localhost')

gvot/urls.py

@@ -9,14 +9,12 @@ from wagtail.documents import urls as wagtaildocs_urls
 from .base import views
 
 urlpatterns = [
-    path('django-admin/', admin.site.urls),
-
     # Wagtail's applications
     path('admin/', include(wagtailadmin_urls)),
     path('documents/', include(wagtaildocs_urls)),
 
     # Local applications
-    # ...
+    path('docs/', include('docs.urls')),
 ]
 
 if settings.DEBUG:

requirements/base.txt

@@ -10,3 +10,9 @@ django-mailer >=2.0,<2.1 # https://github.com/pinax/django-mailer
 wagtail >=2.7,<2.8  # https://wagtail.io
 wagtailembedpeertube # https://forge.cliss21.org/cliss21/wagtailembedpeertube
 wagtailmenus >=3.0,<3.1  # https://github.com/rkhleics/wagtailmenus
+
+# Documentation
+# ------------------------------------------------------------------------------
+sphinx
+sphinx-rtd-theme
+django-docs