Documentation update.

doc/extending/events.rst

@@ -47,6 +47,396 @@ Read further to get a complete list and description of all available events.
 Supported events
 ****************
 
+AccountCreated
+==============
+
+Raised when a new account is created.
+
+*Callback prototype*::
+
+  def callback(account): pass
+
+* ``account`` is the newly created account (``User`` instance)
+
+AccountDeleted
+==============
+
+Raised when an existing account is deleted.
+
+*Callback prototype*::
+
+  def callback(account): pass
+
+* ``oldaccount`` is the account that is going to be deleted
+  
+AccountModified
+===============
+
+Raised when an existing account is modified.
+
+*Callback prototype*::
+
+  def callback(oldaccount, newaccount): pass
+
+* ``oldaccount`` is the account before it is modified
+
+* ``newaccount`` is the account after the modification
+
+AdminMenuDisplay
+================
+
+Raised when an admin menu is about to be displayed.
+
+*Callback prototype*::
+
+  def callback(target, user): pass
+
+The ``target`` argument indicates which menu is being
+displayed. Possible values are:
+
+* ``admin_menu_box`` : corresponds to the menu bar available inside administration pages
+* ``top_menu`` : corresponds to the top black bar
+
+See :ref:`usermenudisplay` for a description of what callbacks that
+listen to this event must return.
+
+CanCreate
+=========
+
+Raised just before a user tries to create a new object.
+
+*Callback prototype*::
+
+  def callback(user): pass
+
+* ``user`` is a ``User`` instance
+
+Return ``True`` or ``False`` to indicate if this user can respectively
+create or not create a new ``Domain`` object.
+
+CheckExtraAccountForm
+=====================
+
+When an account is being modified, this event lets extensions check if
+this account is concerned by a specific form.
+
+*Callback prototype*::
+
+  def callback(account, form): pass
+
+* ``account`` is the ``User`` instance beeing modified
+
+* ``form`` is a dictionnary (same content as for ``ExtraAccountForm``)
+
+Callbacks listening to this event must return a list containing one
+Boolean.
+
+CreateDomain
+============
+
+Raised when a new domain is created. 
+
+*Callback prototype*::
+
+  def callback(user, domain): pass
+
+* ``user`` corresponds to the ``User`` object creating the domain (its owner)
+* ``domain`` is a ``Domain`` instance
+
+CreateMailbox
+=============
+
+Raised when a new mailbox is created.
+
+*Callback prototype*::
+
+  def callback(user, mailbox): pass
+
+* ``user`` is the new mailbox's owner (``User`` instance)
+* ``mailbox`` is the new mailbox (``Mailbox`` instance)
+
+DeleteDomain
+============
+
+Raised when an existing domain is about to be deleted.
+
+*Callback prototype*::
+
+  def callback(domain): pass
+
+* ``domain`` is a ``Domain`` instance
+
+DeleteMailbox
+=============
+
+Raised when an existing mailbox is about to be deleted. 
+
+*Callback prototype*::
+
+  def callback(mailbox): pass
+
+* ``mailbox`` is a ``Mailbox`` instance
+
+DomainAliasCreated
+==================
+
+Raised when a new domain alias is created.
+
+*Callback prototype*::
+
+  def callback(user, domain_alias): pass
+
+* ``user`` is the new domain alias owner (``User`` instance)
+* ``domain_alias`` is the new domain alias (``DomainAlias`` instance)
+
+DomainAliasDeleted
+==================
+
+Raised when an existing domain alias is about to be deleted. 
+
+*Callback prototype*::
+
+  def callback(domain_alias): pass
+
+* ``domain_alias`` is a ``DomainAlias`` instance
+
+ExtDisabled
+===========
+
+Raised just after an extension has been disabled. 
+
+*Callback prototype*::
+
+  def callback(extension): pass
+
+* ``extension`` is an ``Extension`` instance
+
+ExtEnabled
+==========
+
+Raised just after an extension has been activated. 
+
+*Callback prototype*::
+
+  def callback(extension): pass
+
+* ``extension`` is an ``Extension`` instance
+
+ExtraAccountForm
+================
+
+Let extensions add new forms to the account edition form (the one with
+tabs).
+
+*Callback prototype*::
+
+  def callback(user, account): pass
+
+* ``user`` is a ``User`` instance corresponding to the currently
+  logged in user
+
+* ``account`` is the account beeing modified (``User`` instance)
+
+Callbacks listening to the event must return a list of dictionnaries,
+each one must contain at least three keys::
+
+  {"id" : "<the form's id>",
+   "title" : "<the title used to present the form>",
+   "cls" : TheFormClassName}
+
+ExtraAdminContent
+=================
+
+Let extensions add extra content into the admin panel.
+
+*Callback prototype*::
+
+  def callback(user, target, currentpage): pass
+
+* ``user`` is a ``User`` instance corresponding to the currently
+  logged in user
+
+* ``target`` is a string indicating the place where the content will
+  be displayed. Possible values are : ``leftcol``
+
+* ``currentpage`` is a string indicating which page (or section) is
+  displayed. Possible values are : ``domains``, ``identities``
+
+Callbacks listening to this event must return a list of string.
+
+ExtraDomainForm
+===============
+
+Let extensions add new forms to the domain edition form (the one with
+tabs).
+
+*Callback prototype*::
+
+  def callback(user, domain): pass
+
+* ``user`` is a ``User`` instance corresponding to the currently
+  logged in user
+
+* ``domain`` is the domain beeing modified (``Domain`` instance)
+
+Callbacks listening to the event must return a list of dictionnaries,
+each one must contain at least three keys::
+
+  {"id" : "<the form's id>",
+   "title" : "<the title used to present the form>",
+   "cls" : TheFormClassName}
+
+FillAccountInstances
+====================
+
+When an account is beeing modified, this event is raised to fill extra
+forms.
+
+*Callback prototype*::
+
+  def callback(user, account, instances): pass
+
+* ``user`` is a ``User`` instance corresponding to the currently
+  logged in user
+
+* ``account`` is the ``User`` instance beeing modified
+
+* ``instances`` is a dictionnary where the callback will add
+  information needed to fill a specific form
+
+FillDomainInstances
+===================
+
+When a domain is beeing modified, this event is raised to fill extra
+forms.
+
+*Callback prototype*::
+
+  def callback(user, domain, instances): pass
+
+* ``user`` is a ``User`` instance corresponding to the currently
+  logged in user
+
+* ``domain`` is the ``Domain`` instance beeing modified
+
+* ``instances`` is a dictionnary where the callback will add
+  information needed to fill a specific form
+
+GetAnnouncement
+===============
+
+Some places in the interface let plugins add their own announcement
+(ie. message). 
+
+*Callback prototype*::
+
+  def callback(target): pass
+
+* ``target`` is a string indicating the place where the announcement
+  will appear:
+
+* ``loginpage`` : corresponds to the login page
+
+Callbacks listening to this event must return a list of string.
+
+.. _getextraroles:
+
+GetExtraRoles
+=============
+
+Let extensions define new administrative roles.
+
+*Callback prototype*::
+
+  def callback(user): pass
+
+* ``user`` is a ``User`` instance corresponding to the currently
+  logged in user
+
+Callbacks listening to this event must return a list of 2uple (two
+strings) which respect the following format: ``(value, label)``.
+
+GetStaticContent
+================
+
+Let extensions add static content (ie. CSS or javascript) to default
+pages. It is pretty useful for functionalities that don't need a
+template but need javascript stuff.
+
+*Callback prototype*::
+
+  def callback(user): pass
+
+* ``user`` is a ``User`` instance corresponding to the currently
+  logged in user
+
+Callbacks listening to this event must return a list of string.
+
+MailboxAliasCreated
+===================
+
+Raised when a new mailbox alias is created.
+
+*Callback prototype*::
+
+  def callback(user, mailbox_alias): pass
+
+* ``user`` is the new domain alias owner (``User`` instance)
+* ``mailbox_alias`` is the new mailbox alias (``Alias`` instance)
+
+MailboxAliasDeleted
+===================
+
+Raised when an existing mailbox alias is about to be deleted. 
+
+*Callback prototype*::
+
+  def callback(mailbox_alias): pass
+
+* ``mailbox_alias`` is an ``Alias`` instance
+
+ModifyMailbox
+=============
+
+Raised when an existing mailbox is modified. 
+
+*Callback prototype*::
+
+  def callback(newmailbox, oldmailbox): pass
+
+* ``newmailbox`` is a ``Mailbox`` instance containing the new values
+* ``oldmailbox`` is a ``Mailbox`` instance containing the old values
+
+PasswordChange
+==============
+
+Raised just before a *password change* action. 
+
+*Callback prototype*::
+
+  def callback(user): pass
+
+* ``user`` is a ``User`` instance
+
+Callbacks listening to this event must return a list containing either
+``True`` or ``False``. If at least one ``True`` is returned, the
+*password change* will be cancelled (ie. changing the password for
+this user is disabled).
+
+TopNotifications
+================
+
+Let extensions add custom content into the top bar.
+
+*Callback prototype*::
+
+  def callback(user): pass
+
+* ``user`` is a ``User`` instance corresponding to the currently
+  logged in user
+
+Callbacks listening to this event must return a list of string.
+
 UserLogin
 =========
 
@@ -79,9 +469,10 @@ Raised when a user menu is about to be displayed.
 The ``target`` argument indicates which menu is being
 displayed. Possible values are:
 
-* ``uprefs_menu`` : corresponds to the menu bar available inside the
+* ``options_menu``: corresponds to the top-right user menu
+* ``uprefs_menu``: corresponds to the menu bar available inside the
   *User preferences* page
-* ``top_menu`` : corresponds to the top blue bar
+* ``top_menu``: corresponds to the top black bar
 
 All the callbacks that listen to this event must return a list of
 dictionnaries (corresponding to menu entries). Each dictionnary must
@@ -89,355 +480,4 @@ contain at least the following keys::
 
   {"name" : "a_name_without_spaces",
    "label" : _("The menu label"),
-   "url" : reverse("your_view"),   # can be set to ""
-   "img" : static_url("your_pic")} # can be set to ""
-
-AdminMenuDisplay
-================
-
-Raised when an admin menu is about to be displayed.
-
-*Callback prototype*::
-
-  def callback(target, user): pass
-
-The ``target`` argument indicates which menu is being
-displayed. Possible values are:
-
-* ``admin_menu_box`` : corresponds to the menu bar available inside administration pages
-* ``top_menu`` : corresponds to the *Admin* dropdown menu located inside the top blue bar
-
-See :ref:`usermenudisplay` for a description of what callbacks that
-listen to this event must return.
-
-GetStaticContent
-================
-
-Let extensions add static content (ie. CSS or javascript) to default
-pages. It is pretty useful for functionalities that don't need a
-template but need javascript stuff.
-
-*Callback prototype*::
-
-  def callback(user): pass
-
-* ``user`` is a ``User`` instance corresponding to the currently
-  logged in user
-
-Callbacks listening to this event must return a list of string.
-
-CanCreate
-=========
-
-Raised just before a user tries to create a new object.
-
-*Callback prototype*::
-
-  def callback(user): pass
-
-* ``user`` is a ``User`` instance
-
-Return ``True`` or ``False`` to indicate if this user can respectively
-create or not create a new ``Domain`` object.
-
-CreateDomain
-============
-
-Raised when a new domain is created. 
-
-*Callback prototype*::
-
-  def callback(user, domain): pass
-
-* ``user`` corresponds to the ``User`` object creating the domain (its owner)
-* ``domain`` is a ``Domain`` instance
-
-DeleteDomain
-============
-
-Raised when an existing domain is about to be deleted.
-
-*Callback prototype*::
-
-  def callback(domain): pass
-
-* ``domain`` is a ``Domain`` instance
-
-DomainAliasCreated
-==================
-
-Raised when a new domain alias is created.
-
-*Callback prototype*::
-
-  def callback(user, domain_alias): pass
-
-* ``user`` is the new domain alias owner (``User`` instance)
-* ``domain_alias`` is the new domain alias (``DomainAlias`` instance)
-
-DomainAliasDeleted
-==================
-
-Raised when an existing domain alias is about to be deleted. 
-
-*Callback prototype*::
-
-  def callback(domain_alias): pass
-
-* ``domain_alias`` is a ``DomainAlias`` instance
-
-CreateMailbox
-=============
-
-Raised when a new mailbox is created.
-
-*Callback prototype*::
-
-  def callback(user, mailbox): pass
-
-* ``user`` is the new mailbox's owner (``User`` instance)
-* ``mailbox`` is the new mailbox (``Mailbox`` instance)
-
-DeleteMailbox
-=============
-
-Raised when an existing mailbox is about to be deleted. 
-
-*Callback prototype*::
-
-  def callback(mailbox): pass
-
-* ``mailbox`` is a ``Mailbox`` instance
-
-ModifyMailbox
-=============
-
-Raised when an existing mailbox is modified. 
-
-*Callback prototype*::
-
-  def callback(newmailbox, oldmailbox): pass
-
-* ``newmailbox`` is a ``Mailbox`` instance containing the new values
-* ``oldmailbox`` is a ``Mailbox`` instance containing the old values
-
-MailboxAliasCreated
-===================
-
-Raised when a new mailbox alias is created.
-
-*Callback prototype*::
-
-  def callback(user, mailbox_alias): pass
-
-* ``user`` is the new domain alias owner (``User`` instance)
-* ``mailbox_alias`` is the new mailbox alias (``Alias`` instance)
-
-MailboxAliasDeleted
-===================
-
-Raised when an existing mailbox alias is about to be deleted. 
-
-*Callback prototype*::
-
-  def callback(mailbox_alias): pass
-
-* ``mailbox_alias`` is an ``Alias`` instance
-
-AccountCreated
-==============
-
-Raised when a new account is created.
-
-*Callback prototype*::
-
-  def callback(account): pass
-
-* ``account`` is the newly created account (``User`` instance)
-
-AccountModified
-===============
-
-Raised when an existing account is modified.
-
-*Callback prototype*::
-
-  def callback(oldaccount, newaccount): pass
-
-* ``oldaccount`` is the account before it is modified
-
-* ``newaccount`` is the account after the modification
-
-AccountDeleted
-==============
-
-Raised when an existing account is deleted.
-
-*Callback prototype*::
-
-  def callback(account): pass
-
-* ``oldaccount`` is the account that is going to be deleted
-
-ExtraAccountForm
-================
-
-Let extensions add new forms to the global account edition form (the
-one with tabs).
-
-*Callback prototype*::
-
-  def callback(user, account): pass
-
-* ``user`` is a ``User`` instance corresponding to the currently
-  logged in user
-
-* ``account`` is the account beeing modified (``User`` instance)
-
-Callbacks listening to the event must return a list of dictionnaries,
-each one must contain at least three keys::
-
-  {"id" : "<the form's id>",
-   "title" : "<the title used to present the form>",
-   "cls" : TheFormClassName}
-
-CheckExtraAccountForm
-=====================
-
-When an account is being modified, this event lets extensions check if
-this account is concerned by a specific form.
-
-*Callback prototype*::
-
-  def callback(account, form): pass
-
-* ``account`` is the ``User`` instance beeing modified
-
-* ``form`` is a dictionnary (same content as for ``ExtraAccountForm``)
-
-Callbacks listening to this event must return a list containing one
-Boolean.
-
-FillAccountInstances
-====================
-
-When an account is beeing modified, this event is raised to fill extra
-forms.
-
-*Callback prototype*::
-
-  def callback(user, account, instances): pass
-
-* ``user`` is a ``User`` instance corresponding to the currently
-  logged in user
-
-* ``account`` is the ``User`` instance beeing modified
-
-* ``instances`` is a dictionnary where the callback will add
-  information needed to fill a specific form
-
-.. _getextraroles:
-
-GetExtraRoles
-=============
-
-Let extensions define new administrative roles.
-
-*Callback prototype*::
-
-  def callback(user): pass
-
-* ``user`` is a ``User`` instance corresponding to the currently
-  logged in user
-
-Callbacks listening to this event must return a list of 2uple (two
-strings) which respect the following format: ``(value, label)``.
-
-ExtEnabled
-==========
-
-Raised just after an extension has been activated. 
-
-*Callback prototype*::
-
-  def callback(extension): pass
-
-* ``extension`` is an ``Extension`` instance
-
-ExtDisabled
-===========
-
-Raised just after an extension has been disabled. 
-
-*Callback prototype*::
-
-  def callback(extension): pass
-
-* ``extension`` is an ``Extension`` instance
-
-GetAnnouncement
-===============
-
-Some places in the interface let plugins add their own announcement
-(ie. message). 
-
-*Callback prototype*::
-
-  def callback(target): pass
-
-* ``target`` is a string indicating the place where the announcement
-  will appear:
-
-* ``loginpage`` : corresponds to the login page
-
-Callbacks listening to this event must return a list of string.
-
-TopNotifications
-================
-
-Let extensions add custom content into the top bar.
-
-*Callback prototype*::
-
-  def callback(user): pass
-
-* ``user`` is a ``User`` instance corresponding to the currently
-  logged in user
-
-Callbacks listening to this event must return a list of string.
-
-ExtraAdminContent
-=================
-
-Let extensions add extra content into the admin panel.
-
-*Callback prototype*::
-
-  def callback(user, target, currentpage): pass
-
-* ``user`` is a ``User`` instance corresponding to the currently
-  logged in user
-
-* ``target`` is a string indicating the place where the content will
-  be displayed. Possible values are : ``leftcol``
-
-* ``currentpage`` is a string indicating which page (or section) is
-  displayed. Possible values are : ``domains``, ``identities``
-
-Callbacks listening to this event must return a list of string.
-
-PasswordChange
-==============
-
-Raised just before a *password change* action. 
-
-*Callback prototype*::
-
-  def callback(user): pass
-
-* ``user`` is a ``User`` instance
-
-Callbacks listening to this event must return a list containing either
-``True`` or ``False``. If at least one ``True`` is returned, the
-*password change* will be cancelled (ie. changing the password for
-this user is disabled).
+   "url" : reverse("your_view")}

doc/getting_started/configuration.rst

@@ -86,6 +86,8 @@ manipulate directories in vmail's homedir. To do so, edit the
 
   <user_that_runs_modoboa> ALL=(vmail) NOPASSWD: ALL
 
+.. _timezone_lang:
+
 **********************
 Time zone and language
 **********************

doc/getting_started/install.rst

@@ -16,10 +16,7 @@ Requirements
 * `rrdtool python binding <http://oss.oetiker.ch/rrdtool/>`_
 * `sievelib python module <http://pypi.python.org/pypi/sievelib>`_
 
-Optional
-========
-
-* `ckeditor version 3.4.1+ <http://ckeditor.com/>`_
+.. _get_modoboa:
 
 ***********
 Get Modoboa
@@ -51,13 +48,14 @@ Database
 Thanks to *django*, Modoboa supports several databases. Depending on
 the one you will use, you must install the appropriate python package:
 
-* `MySQL <http://www.mysql.com>`_: `mysqldb <http://mysql-python.sourceforge.net/>`_
-* `PostgreSQL <http://www.postgresql.org>`_ : `psycopg2 <http://initd.org/psycopg/>`_
-* `SQLite <http://www.sqlite.org>`_: already shipped with *Python*
+* `mysqldb <http://mysql-python.sourceforge.net/>`_ for `MySQL <http://www.mysql.com>`_
+* `psycopg2 <http://initd.org/psycopg/>`_ for `PostgreSQL <http://www.postgresql.org>`_
 
 Then, create a user and a database that will be used by Modoboa. Make
 sure your database is using UTF8 as a default charset.
 
+.. _deployment:
+
 **********
 Deployment
 **********
@@ -91,5 +89,15 @@ available:
 * Username: ``admin``
 * Password: ``password``
 
-It is **strongly** recommanded to change this password the first time
+It is **strongly** recommended to change this password the first time
 you log into Modoboa.
+
+To check if your installation works, just launch the embedded HTTP
+server::
+
+  $ python manage.py runserver
+
+You should be able to access your site at http://locahost:8000/.
+
+For a production environnement, we recommend using a stable webserver
+like :ref:`apache2` or :ref:`nginx-label`.

doc/getting_started/plugins.rst

@@ -29,6 +29,8 @@ to domain administrators.
 If you don't want to limit a particular object type, just set the
 associated value to -1.
 
+.. _amavis_frontend:
+
 ********************
 Amavisd-new frontend
 ********************
@@ -171,6 +173,8 @@ Here is a link example::
 
   http://<modoboa_url>/quarantine/%i/?rcpt=%R&secret_id=[:secret_id]
 
+.. _stats:
+
 ********************
 Graphical statistics
 ********************
@@ -207,6 +211,8 @@ Replace ``<modoboa_site>`` with the path of your Modoboa instance.
 
 Graphics will be automatically created after each parsing.
 
+.. _postfix_ar:
+
 ***************************
 Postifx auto-reply messages
 ***************************
@@ -323,11 +329,18 @@ The size of each attachment sent with messages is limited. You can
 change the default value by modifying the ``MAX_ATTACHMENT_SIZE``
 parameter.
 
-Using a rich editor
-===================
+Using CKeditor
+==============
 
-CKeditor is supported by Modoboa. To use it, first download it from
-`the official website <http://ckeditor.com/>`_, then extract the tarball::
+Modoboa supports CKeditor to compose HTML messages. To use it, first
+download it from `the official website <http://ckeditor.com/>`_, then
+extract the tarball::
 
   $ cd <modoboa_site_dir>
-  $ 
+  $ tar xzf /path/to/ckeditor/tarball.tag.gz -C sitestatic/js/
+
+And you're done!
+
+Now, each user has the possibility to choose between CKeditor and the
+raw text editor to compose their messages. (see *User > Settings >
+Preferences > Webmail*)

doc/getting_started/upgrade.rst

@@ -5,24 +5,59 @@ Upgrading an existing installation
 This section regroups all the upgrade procedures required to use
 newest versions of Modoboa.
 
+.. note::
+   Before running a migration, we recommend that you make
+   a copy of your existing database.
+
 **************
 Latest version
 **************
 
-FIXME
+Starting with version 0.9.1, Modoboa comes as a standard django
+application. Fetch the latest version (see :ref:`get_modoboa`) and
+install it.
 
-**************
-Modoboa <= 0.9
-**************
+``pip`` users, just run the following command::
+
+  $ pip install --upgrade modoboa
+
+Then, follow the common procedure::
+
+  $ cd <modoboa_instance_dir>
+  $ python manage.py syncdb --migrate
+  $ python collectstatic
+
+Finally, refer to this page to see if the version you're installing
+requires specific operations.
+
+0.9.1: standard django application and more
+===========================================
+
+For this version, we recommend to install a new instance (see
+:ref:`deployment`) in a different directory.
+
+Then, copy the following content from the old installation to the new
+one:
+
+* The ``media`` directory
+* The directory containing RRD files if you use the :ref:`stats` plugin
+
+Don't copy the old *settings.py* file, just keep the new one and
+modify it (see :ref:`database` and :ref:`timezone_lang`).
+
+Finally, check the :ref:`amavis_frontend`, :ref:`postfix_ar` and
+:ref:`stats` chapters (depending on those you use) because the
+provided cron scripts have been changed, you must update the way you
+call them.
+
+********************
+Modoboa prior to 0.9
+********************
 
 First, decompress the new tarball at the same location than your
 current installation. Then, check if the new version you're installing
 requires a migration.
 
-.. note::
-   Before executing a schema/data migration, I recommend that you make
-   a copy of your existing database.
-
 0.9: global UI refactoring, new *limits* extension and more
 ===========================================================
 

doc/integration/web_servers.rst

@@ -36,6 +36,8 @@ following inside::
 This is one possible configuration. Note that you will certainly need more
 configuration in order to launch Apache.
 
+.. _nginx-label:
+
 *****
 Nginx
 *****