Update documentation

05c1d473 · Christophe Siraut · 47cf5239 · 05c1d473
Commit 05c1d473 authored Jul 30, 2014 by Christophe Siraut
--- a/docs/nuages.rst
+++ b/docs/nuages.rst
 ======
 Nuages
 ======
-----------------
-Easy poll sharing
-----------------

-Nuages aims to provide a collaborative meeting poll system, similar to doodle or rdvz. It is build in python, using the django framework and a little of javascript. This application was named after Django's famous song. Feedback and collaboration are welcome at nuages @lists.domainepublic.net
+''Easy poll sharing''
+
+A collaborative meeting poll system, similar to doodle or rdvz. This application was named after Django's famous song and because computer work is easier when its cloudy. It is build in python, using the django framework and a little of javascript.
+
+Feedback and collaboration are welcome at nuages@lists.domainepublic.net. (Inscription to the mailing list is recommended before posting) We have a project page at projets.domainepublic.net.
+
+ Get Nuages:: git clone http://git.domainepublic.net/git/nuages.git
+ Browse changes:: http://git.domainepublic.net/?p=nuages.git
+ Sources freely available under license GPL. 

 The project uses the following django applications:

@@ -13,48 +18,24 @@ The project uses the following django applications:
    - django-datetime-widget
    - django-bootstrap-staticfiles

-Automated installation
-======================
-Using setuptools all dependencies will be installed:
-
-  # python setup.py install
-
-This can also be achieved in a virtualenv:
-
-  # virtualenv --system-site-packages env
-  # source env/bin/activate
-  # python setup.py install
-
-Manual installation
-===================
-Install required dependencies and copy nuages to /usr/local/lib.
-
-On debian and derivatives one can install it as follow:
-
-  # aptitude install python-django python-django-registration
-  # pip install django-datetime-widget django-bootstrap-staticfiles django-jquery
-
-Local settings
-==============
-Use local_settings.py and local_urls.py to customize your installation when needed.
-
-Translation
-===========
-Create/update a translation file::
-
-    # django-admin makemessages -l fr
+Installation
+============

-Edit and translate the translation file::
+Normal installation
+----------------------
+On debian derivatives Nuages can can be installed and configured with dpkg:

-    # vi locale/fr/LC_MESSAGES/django.po
+  dpkg -i python-nuages*.deb nuages*.deb

-Compile translated messages/update a translation file::
+Python package installation
+---------------------------
+Using setuptools all dependencies will be installed:

-    # make translation
+  # python setup.py install

-Dev installation
-================
-Install python-django package (>=1.3)
+Development installation
+------------------------
+Install python-django package (>=1.5)
 Clone nuages archive somewhere in your home folder::

    # cd
@@ -63,10 +44,12 @@ Clone nuages archive somewhere in your home folder::
 You can have local customizations in the nuages/local_settings.py file (and avoid modify the original settings.py)::

    # vi nuages/local_settings.py
+    # vi nuages/local_urls.py

 Build nuages database::

    # ./manage.py syncdb
+    # ./manage.py migrate meetingpoll

 Start the python webserver::

@@ -74,48 +57,20 @@ Start the python webserver::

 You should have the application running at http://127.0.0.1:8000

-Apache installation
-===================
-Install python-django package (>=1.3)
-Copy nuages to /usr/local/lib/nuages::
-
-    # cd /usr/local/lib
-    # git clone http://git.domainepublic.net/git/nuages.git 
+Configuration
+=============
+Web server
+----------
+There are several ways to configure Apache and python, we use wsgi by default. After installing the package, two example configuration are available in /etc/apache2/sites-available. (Note if you use Apache < 1.4, you need to remove the "require" directive)

 You can have local customizations in the local_settings.py file. (Optionally set DEBUG option to False)::

-    # vi /usr/local/lib/nuages/nuages/local_settings.py
-
-There are several ways to configure Apache and python, we recommend wsgi, simply install libapache2-mod-wsgi, and add the following to /etc/apache2/sites-available/nuages, replacing ServerName accordingly::
-
-    <VirtualHost *:80>
-      
-      ServerName localhost.locadomain
-      Alias /static/ /usr/local/lib/nuages/staticroot/
-      WSGIScriptAlias / /usr/local/lib/nuages/nuages/wsgi.py
-
-      <Directory /usr/local/lib/nuages/nuages>
-        <Files wsgi.py>
-        Order deny,allow
-        Allow from all
-        </Files>
-      </Directory>
-
-      <Directory /usr/local/lib/nuages/staticroot>
-        Order deny,allow
-        Allow from all
-      </Directory>
-
-    </VirtualHost>
-
-Build database, collect static files and set permissions::
-
-  # make update 
+    # vi /etc/nuages/local_settings.py

 Set domain name: Point your browser to /admin/sites/site/1/ and modify the entry from "example.com" to your domain name.

 SSL
-===
+---
 We recommend using SSL for all transactions and adding the following settings to your local_settings.py::

  SESSION_COOKIE_SECURE = True
@@ -125,26 +80,9 @@ We recommend using SSL for all transactions and adding the following settings to
        '.domainepublic.net.', # Also allow FQDN and subdomains
  ]

-Testing
-=======
-In order to test Nuages, you need the following dependencies::
-
-  webtest
-  coverage
-  django_webtest
-  django-discover-runner
-
-On debian::
-
-  # aptitude install python-webtest python-coverage python-pip
-  # pip install django_webtest django-discover-runner
-
-You can now validate your modifications with::
-
-  # make test

 Email Service
-=============
+-------------
 Django is expecting a working SMTP server listening at localhost, sendmail for instance.

 Another option is to add attributes in local_settings.py, so django can connect to an external server for the mail delivery. To enable this, we only have to add these lines::
@@ -156,20 +94,43 @@ Another option is to add attributes in local_settings.py, so django can connect
  EMAIL_HOST_PASSWORD = 'password'
  EMAIL_USE_TLS = False

-Update
-======
-In order to update your nuages installation::
+Contributing
+============
+Patches are welcom: please send us a mail or join Domaine Public irc to let us know your propositions.
+
+Testing
+-------
+Please validate your modifications with::
+
+  # make test
+
+Translations
+------------
+Nuages is avalable in many languages. If you have a little time and want help translate Nuages in your language, your help is welcome. You can translate the following file to your language, and present it on the mailing list::
+
+ http://git.domainepublic.net/?p=nuages.git;a=blob_plain;f=locale/fr/LC_MESSAGES/django.po
+
+Adding a new translation
+~~~~~~~~~~~~~~~~~~~~~~~~ 
+Create/update a translation file::
+
+    # django-admin makemessages -l fr
+
+Edit and translate the translation file::
+
+    # vi locale/fr/LC_MESSAGES/django.po
+
+Compile translated messages/update a translation file::
+
+    # make translation

-  # make update
+Migrations
+==========
+Migrations are handled automatically through South.

-Migration
-=========
-When models change, we need to perform some manual steps to keep existing data. The following example backups all databases to json files, and resets only the poll table::
+When migrating from a Nuages version < 0.20140730, one need to manually do::

-  # mkdir fixtures
-  # APPS="account auth meetingpoll poll"
-  # for APP in $APPS; do ./manage.py dumpdata $APP --indent=2 > fixtures/$APP.json; done
-  # git pull
-  # ./manage.py flush poll
-  # ./manage.py loaddata fixtures/*.json
+  # copy old database (/usr/local/lib/nuages.sqlite) to /var/lib/nuages/db.sqlite
+  nuages syncdb
+  nuages migrate meetingpoll 0001 --fake