Move the plugins documentation

(use automodule directive & docstrings)

25 files changed, 927 insertions, 13 deletions

diff --git a/plugins/alias.py b/plugins/alias.py
index a3843f35..80efe5bc 100644
--- a/plugins/alias.py
+++ b/plugins/alias.py
@@ -1,7 +1,41 @@
 """
-Alias plugin.
+Installation
+------------
+You only have to load the plugin:
+
+``/load alias``
+
+Usage
+-----
+
+This plugin defines two new global commands: :term:`/alias` and :term:`/unalias`.
+
+.. glossary::
+
+    /alias
+        **Usage:** ``/alias <name> <command> [args]``
+
+        This command will create a new command, named ``name`` (and callable with
+        ``/name``), that runs ``/command``, with ``[args]`` as fixed args for the command.
+        When you run the alias, you can also pass parameters to it, that will be fed
+        to the original command.
+
+        Example: ::
+
+            /alias toto say "koin "
+
+        Will bind ``/say koin `` to ``/toto``, so this alias will work in any
+        Chat tab. If someone calls it with ::
+
+            /toto koin
+
+        Poezio will then execute ``/say koin koin``.
+
+    /unalias
+        **Usage:** ``/unalias <name>``
+
+        This command removes a defined alias.
 
-Allows the creation and the removal of personal aliases.
 """
 
 from plugin import BasePlugin
diff --git a/plugins/amsg.py b/plugins/amsg.py
index 57a37255..c330373f 100644
--- a/plugins/amsg.py
+++ b/plugins/amsg.py
@@ -1,5 +1,25 @@
-# A simple broadcast plugin
+"""
+This plugin broadcasts a message to all your joined rooms.
 
+.. note:: With great power comes great responsability.
+          Use with moderation.
+
+Installation
+------------
+You only have to load the plugin.::
+
+    /load amsg
+
+Command
+-------
+
+.. glossary::
+
+    /amsg
+        **Usage:** ``/amsg <message>``
+
+
+"""
 from plugin import BasePlugin
 from tabs import MucTab
 
diff --git a/plugins/day_change.py b/plugins/day_change.py
index 179bfd98..d9cd3197 100644
--- a/plugins/day_change.py
+++ b/plugins/day_change.py
@@ -1,3 +1,15 @@
+"""
+This plugin adds a message at 00:00 in each of your chat tabs saying that the
+date has changed.
+
+Installation
+------------
+You only have to load the plugin.::
+
+    /load day_change
+
+"""
+
 from gettext import gettext as _
 from plugin import BasePlugin
 import datetime
diff --git a/plugins/display_corrections.py b/plugins/display_corrections.py
index cad5a327..c7617b3e 100644
--- a/plugins/display_corrections.py
+++ b/plugins/display_corrections.py
@@ -1,6 +1,33 @@
-# A plugin that adds the /display_corrections command, to view the previous
-# versions of a corrected message.
+"""
+Lists old versions of a corrected message.
 
+Installation
+------------
+::
+
+    /load display_corrections
+
+Usage
+-----
+
+.. glossary::
+
+    /display_corrections
+        **Usage:** ``/display_corrections [number]``
+
+        This command lists the old versions of a message.
+
+        Without argument, it will list the last corrected message if there
+        is any. If you give an integer as an argument, ``/display_corrections``
+        will go back gradually in the buffer to find the message matching
+        that number (starting from 1, for the last corrected message).
+
+        If you are scrolling in the buffer, Poezio will list the corrected messages
+        starting from the first you can see.  (although there are some problems with
+        multiline messages).
+
+
+"""
 from plugin import BasePlugin
 from common import shell_split
 import tabs
diff --git a/plugins/double.py b/plugins/double.py
index 597ab242..02c7ddcd 100644
--- a/plugins/double.py
+++ b/plugins/double.py
@@ -1,3 +1,15 @@
+"""
+Double the first word of any message you send in a :ref:`muctab`, making you appear retarded.
+
+Installation
+------------
+
+You only have to load the plugin:
+
+.. code-block:: none
+
+    /load double
+"""
 from plugin import BasePlugin
 
 class Plugin(BasePlugin):
diff --git a/plugins/exec.py b/plugins/exec.py
index 4dbe9590..10681713 100644
--- a/plugins/exec.py
+++ b/plugins/exec.py
@@ -1,4 +1,46 @@
-# A plugin that can execute a command and send the result in the conversation
+"""
+This plugin lets you execute a system command through poezio.
+
+Installation
+------------
+
+You only have to load the plugin. ::
+
+    /load exec
+
+Usage
+-----
+
+.. warning:: Running commands that start a daemon or an interface is not a good
+             idea.
+
+.. glossary::
+
+    /exec
+        **Usage:** ``/exec [-o|-O] <command>``
+
+        Execute a system command.
+
+        ::
+
+            /exec command
+
+        Will give you the result in the information buffer.
+
+        ::
+
+            /exec -o command
+
+        Will send the result of the command into the current tab, if possible.
+
+        ::
+
+            /exec -O command
+
+        Will send the result of the command and the command summary into the current
+        tab, if possible.
+
+"""
 
 from plugin import BasePlugin
 import os
diff --git a/plugins/figlet.py b/plugins/figlet.py
index eaf8dab3..9006f793 100644
--- a/plugins/figlet.py
+++ b/plugins/figlet.py
@@ -1,3 +1,23 @@
+"""
+This plugin uses figlet to transform every message into a big ascii-art
+message.
+
+Installation
+------------
+You only have to load the plugin (and have :file:`figlet` installed, of course).
+::
+
+    /load figlet
+
+
+Usage
+-----
+
+Say something in a Chat tab.
+
+.. note:: Can create fun things when used with :ref:`The rainbow plugin <rainbow-plugin>`.
+
+"""
 from plugin import BasePlugin
 import subprocess
 
diff --git a/plugins/gpg/__init__.py b/plugins/gpg/__init__.py
index 9fa8ee13..c6945e18 100644
--- a/plugins/gpg/__init__.py
+++ b/plugins/gpg/__init__.py
@@ -1,3 +1,107 @@
+"""
+This plugin implements the `XEP-0027`_ “Current Jabber OpenPGP Usage”.
+
+This is a plugin used to encrypt one-to-one conversation using the PGP
+encryption method. You can use it if you want really good privacy. Without this
+encryption, your messages are encrypted **at least** from your client (poezio) to
+your server. The message is decrypted by your server and you cannot control the
+encryption method of your messages from your server to your contact’s server
+(unless you are your own server’s administrator), nor from your contact’s
+server to your contact’s client.
+
+This plugin does end-to-end encryption. This means that **only** your contact can
+decrypt your messages, and it is fully encrypted during **all** its travel
+through the internet.
+
+Note that if you are having an encrypted conversation with a contact, you can
+**not** send XHTML-IM messages to him. They will be removed and be replaced by
+plain text messages.
+
+Installation and configuration
+------------------------------
+
+You should autoload this plugin, as it will send your signed presence directly
+on login, making it easier for your contact’s clients to know that you are
+supporting GPG encryption. To do that, use the :term:`plugins_autoload` configuration
+option.
+
+You need to create a plugin configuration file. Create a file named :file:`gpg.cfg`
+into your plugins configuration directory (:file:`~/.config/poezio/plugins` by
+default), and fill it like this:
+
+.. code-block:: ini
+
+    [gpg]
+    keyid = 091F9C78
+    passphrase = your OPTIONAL passphrase
+
+    [keys]
+    example@jabber.org = E3CFCDE2
+    juliet@xmpp.org = EF27ABCD
+
+The ``gpg`` section is about your key. You need to specify the keyid, for the
+key you want to use. You can as well provide a passphrase. If you don’t, you
+should use a gpg agent or something like that that will ask your passphrase
+whenever you need it.
+
+The ``keys`` section contains your contact’s id keys. For each contact you want
+to have encrypted conversations with, add her/his JID associated with the keyid
+of his/her key.
+
+And that’s it, now you need to talk directly to the **full** jid of your
+contacts. Poezio doesn’t let you encrypt messages whom recipients is a bare
+JID.
+
+Additionnal information on GnuPG
+--------------------------------
+
+Create a key
+~~~~~~~~~~~~
+
+To create a personal key, use
+
+.. code-block:: bash
+
+    gpg --gen-key
+
+and follow the instructions.
+
+Keyid
+~~~~~
+The keyid (required in the gpg.cfg configuration file) is a 8 character-long
+key. You can get the ones you created or imported by using the command
+
+.. code-block:: bash
+
+    gpg --list-keys
+
+You will get something like
+
+.. code-block:: none
+
+    pub   4096R/01234567 2011-11-11
+    uid                  Your Name Here (comment) <email@example.org>
+    sub   4096R/AAFFBBCC 2011-11-11
+
+    pub   2048R/12345678 2011-11-12 [expire: 2011-11-22]
+    uid                  A contact’s name (comment) <fake@fake.fr>
+    sub   2048R/FFBBAACC 2011-11-12 [expire: 2011-11-22]
+
+In this example, the keyids are ``01234567`` and  ``12345678``.
+
+Share your key
+~~~~~~~~~~~~~~
+Use:
+
+.. code-block:: bash
+
+    gpg --send-keys --keyserver pgp.mit.edu <keyid>
+
+to upload you public key on a public server.
+
+.. _XEP-0027: http://xmpp.org/extensions/xep-0027.html
+
+"""
 from gpg import gnupg
 from sleekxmpp.xmlstream.stanzabase import JID
 
diff --git a/plugins/iq_show.py b/plugins/iq_show.py
index 06d06d8e..69bd2722 100644
--- a/plugins/iq_show.py
+++ b/plugins/iq_show.py
@@ -1,3 +1,16 @@
+"""
+Show the exchanged IQs (useful for debugging).
+
+Installation
+------------
+
+Load the plugin:
+
+.. code-block:: none
+
+    /load iq_show
+
+"""
 from plugin import BasePlugin
 from sleekxmpp.xmlstream.matcher import StanzaPath
 from sleekxmpp.xmlstream.handler import Callback
diff --git a/plugins/link.py b/plugins/link.py
index 9e8b6f97..a51a8bef 100644
--- a/plugins/link.py
+++ b/plugins/link.py
@@ -1,6 +1,80 @@
-# A plugin that adds the /link command, letting you open links that are pasted
-# in the conversation, without having to click them.
+"""
+Opens links in a browser.
 
+Installation
+------------
+
+First use case: local use
+~~~~~~~~~~~~~~~~~~~~~~~~~
+If you use poezio on your workstation, this is for you.
+You only have to load the plugin: ::
+
+    /load link
+
+Second use case: remote use
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you use poezio through SSH, this is for you.
+
+.. note:: Small explanation: Poezio will create a `Unix FIFO`_ and send the commands in,
+            and you will have to run a dæmon locally with ssh, to get those commands.
+
+First, set the :term:`exec_remote` option in the config file to ``true``. Then select
+the directory you want to put the fifo in (default is the current
+directory, :file:`./`), the :file:`poezio.fifo` file will be created there.
+
+After that, load the plugin: ::
+
+    /load link
+
+And open a link with :term:`/link` (as described below), this will create the FIFO.
+
+You need to grab poezio’s sources on your client computer, or at least the `daemon.py`_
+file.
+
+Finally, on your client computer, run the ssh command:
+
+.. code-block:: bash
+
+    ssh toto@example.org "cat ~/poezio/poezio.fifo" | python3 daemon.py
+
+Usage
+-----
+
+.. glossary::
+
+    /link
+        **Usage:** ``/link [num]``
+
+        This plugin adds a :term:`/link` command that will open the links in ``firefox``. If
+        you want to use another browser, you can use the :term:`/set` command  to change the
+        :term:`browser` option.
+
+
+        :term:`/link` without argument will open the last received link, if any is found.
+        If an integer argument is given, /link will go back gradually in the buffer
+        to open the previous link, and so on.
+
+
+        If you are scrolling in the buffer, poezio will open the links starting from
+        the first you can see. (although there are some problems with multiline
+        messages).
+
+Options
+-------
+
+:term:`exec_remote`
+
+    To execute the command on your client
+
+.. glossary::
+
+    browser
+        Set the default browser started by the plugin
+
+.. _Unix FIFO: https://en.wikipedia.org/wiki/Named_pipe
+.. _daemon.py: http://gitweb.louiz.org/?p=poezio;a=blob_plain;f=src/daemon.py;hb=HEAD
+
+"""
 import re
 
 from plugin import BasePlugin
diff --git a/plugins/mpd_client.py b/plugins/mpd_client.py
index 09a2e5d2..5991422c 100644
--- a/plugins/mpd_client.py
+++ b/plugins/mpd_client.py
@@ -1,4 +1,53 @@
-# a plugin adding a command to manipulate an MPD instance
+"""
+This plugin is here to send what you are listening to in a chat tab.
+
+
+
+Installation
+------------
+
+You need `python-mpd`_, in its python3 version.
+
+Then you can load the plugin.
+
+.. code-block:: none
+
+ /load mpd_client
+
+
+Configuration
+-------------
+
+You have to put the following into :file:`mpd_client.cfg`, as explained in
+the :ref:`plugin-configuration` section.
+
+.. note:: If you do not put anything, the plugin will try to connect to
+        :file:`localhost:6600` with no password.
+
+.. code-block:: ini
+
+    [mpd_client]
+    host = the_mpd_host
+    port = 6600
+    password = password if necessary
+
+
+Usage
+-----
+
+.. glossary::
+
+    /mpd
+        **Usage:** ``/mpd [full]``
+
+        The bare command will show the current song, artist, and album
+
+        ``/mpd full`` will show the current song, artist, and album,
+        plus a nice progress bar in color.
+
+.. _python-mpd: https://github.com/Mic92/python-mpd2
+
+"""
 
 from plugin import BasePlugin
 from common import shell_split
diff --git a/plugins/otr.py b/plugins/otr.py
index 4e900b84..9014a4c6 100644
--- a/plugins/otr.py
+++ b/plugins/otr.py
@@ -1,3 +1,98 @@
+"""
+
+.. warning:: THE OTR LIB IS IN AN EXPERIMENTAL STATE AND SHOULD NOT BE
+            CONSIDERED AS ENTIRELY RELIABLE
+
+This plugin implements `Off The Record messaging`_.
+
+This is a plugin used to encrypt one-to-one conversation using the OTR
+encryption method. You can use it if you want good privacy, deniability,
+authentication, and strong secrecy. Without this
+encryption, your messages are encrypted **at least** from your client (poezio) to
+your server. The message is decrypted by your server and you cannot control the
+encryption method of your messages from your server to your contact’s server
+(unless you are your own server’s administrator), nor from your contact’s
+server to your contact’s client.
+
+This plugin does end-to-end encryption. This means that **only** your contact can
+decrypt your messages, and it is fully encrypted during **all** its travel
+through the internet.
+
+Note that if you are having an encrypted conversation with a contact, you can
+**not** send XHTML-IM messages to him. They will be removed and be replaced by
+plain text messages.
+
+Installation and configuration
+------------------------------
+
+To use the OTR plugin, you must first install libopenotr.
+
+If you use Archlinux, there is a `libopenotr-git`_ package on the AUR.
+
+If not, then you will have to install it by hand.
+
+First, clone the repo and go inside the created directory:
+
+.. code-block:: bash
+
+    git clone https://github.com/teisenbe/libopenotr.git
+    cd libopenotr
+
+Then run autogen.sh and configure
+
+.. code-block:: bash
+
+    sh autogen.sh
+    ./configure --enable-gaping-security-hole
+
+(as of now, you *should* have been warned enough that the library is not finished)
+
+Then compile & install the lib:
+
+.. code-block:: bash
+
+    make
+    sudo make install
+
+Finally, install the python module:
+
+.. code-block:: bash
+
+    python3 setup.py build
+    sudo python3 setup.py install
+
+Usage
+-----
+
+To use OTR, make sure the plugin is loaded (if not, then do ``/load otr``).
+
+Once you are in a private conversation, you have to do a:
+
+
+.. code-block:: none
+
+    /otr start
+
+The status of the OTR encryption should appear in the bar between the chat and
+the input as ``OTR: encrypted``.
+
+
+Once you’re done, end the OTR session with
+
+.. code-block:: none
+
+    /otr end
+
+Known problems
+--------------
+
+Empty messages send when changing status.
+
+.. _Off The Record messaging: http://wiki.xmpp.org/web/OTR
+.. _libopenotr-git:  https://aur.archlinux.org/packages.php?ID=57957
+
+"""
+
 import pyotr
 from sleekxmpp.xmlstream.stanzabase import JID
 
diff --git a/plugins/pacokick.py b/plugins/pacokick.py
index 358df013..bd285db8 100644
--- a/plugins/pacokick.py
+++ b/plugins/pacokick.py
@@ -1,3 +1,25 @@
+"""
+This plugin adds a :term:`/pacokick` command, which is a random kick.
+
+Installation
+------------
+You only have to load the plugin.
+
+.. code-block:: none
+
+    /load pacokick
+
+Usage
+-----
+
+.. glossary::
+
+    /pacokick
+
+        Run the command in a room where you are a moderator to
+        kick someone randomly.
+"""
+
 from random import choice
 from tabs import MucTab
 
diff --git a/plugins/ping.py b/plugins/ping.py
index faf3e97d..c4f56c81 100644
--- a/plugins/ping.py
+++ b/plugins/ping.py
@@ -1,3 +1,35 @@
+"""
+This plugin allows you to ping an entity.
+
+Installation
+------------
+You only have to load the plugin.
+
+.. code-block:: none
+
+    /load ping
+
+Command
+-------
+
+.. glossary::
+
+    /ping
+        **Usage (globally):** ``/ping <jid>``
+
+        **Usage (in a MUC tab):** ``/ping <jid or nick>``
+
+        **Usage (in a conversation tab):** ``/ping [jid]``
+
+        Globally, you can do ``/ping jid@example.com`` to get a ping.
+
+        In a MUC, you can either do it to a JID or a nick (``/ping nick`` or ``/ping
+        jid@example.com``).
+
+        In a private or a direct conversation, you can do ``/ping`` to ping
+        the current interlocutor.
+"""
+
 from plugin import BasePlugin
 from roster import roster
 from common import safeJID
diff --git a/plugins/quote.py b/plugins/quote.py
index 9b1fd9ad..829f251e 100644
--- a/plugins/quote.py
+++ b/plugins/quote.py
@@ -1,3 +1,33 @@
+"""
+This plugin allows you to quote messages easily.
+
+Installation
+------------
+You only have to load the plugin.
+
+.. code-block:: none
+
+    /load quote
+
+Usage
+-------
+
+.. glossary::
+
+    /quote
+        **Usage:** ``/quote <timestamp>``
+
+        Timestamp is in ``HH:MM:SS`` format, and can be completed with [tab].
+
+        Example:
+
+        .. code-block:: none
+
+            /quote 21:12:23
+
+        If there is a message at 21:12:23, it will be put in the input. If there
+        isn’t, you will get a warning.
+"""
 from plugin import BasePlugin
 from xhtml import clean_text
 import common
diff --git a/plugins/rainbow.py b/plugins/rainbow.py
index 4a188b33..0937eeb7 100644
--- a/plugins/rainbow.py
+++ b/plugins/rainbow.py
@@ -1,3 +1,26 @@
+"""
+This plugin colors each character of a message with a random color.
+
+Installation
+------------
+
+You only have to load the plugin.
+
+.. code-block:: none
+
+    /load rainbow
+
+Usage
+-----
+
+.. glossary::
+
+    /rainbow
+
+        Say something in a Chat tab.
+
+.. note:: Can create fun things when used with :ref:`The figlet plugin <figlet-plugin>`.
+"""
 from plugin import BasePlugin
 import xhtml
 import random
diff --git a/plugins/reminder.py b/plugins/reminder.py
index 16a3f710..eb2f9801 100644
--- a/plugins/reminder.py
+++ b/plugins/reminder.py
@@ -1,3 +1,60 @@
+"""
+Installation
+------------
+You only have to load the plugin:
+
+.. code-block:: none
+
+    /load reminder
+
+Usage
+-----
+
+This plugin defines three new global commands: :term:`/remind`,
+:term:`/done`, and :term:`/tasks`.
+
+.. glossary::
+
+    /remind
+        **Usage:** ``/remind <time> <todo>``
+
+        This command will remind you to do ``todo`` every ``time``.
+
+    /done
+        **Usage:** ``/done <id>``
+        Remove a reminder.
+
+        The ``id`` is found using :term:`/tasks`.
+
+
+    /tasks
+
+        Print a list of the tasks, their ids, and their frequency, into the
+        information buffer.
+
+Time format
+-----------
+
+In seconds:
+
+.. code-block:: none
+
+    /remind 600 Work!
+
+Will remind you to work every 10 minutes.
+
+Defining the time in seconds is not really practical, so you can describe it
+with days, hours, and minutes, in a time-string, e.g:
+
+.. code-block:: python
+
+    /remind 1h23m "Get up"
+
+Will remind you to get up every 1 hour 23 minutes.
+
+
+"""
+
 from plugin import BasePlugin
 import curses
 import common
diff --git a/plugins/replace.py b/plugins/replace.py
index abf79648..5f1e33d1 100644
--- a/plugins/replace.py
+++ b/plugins/replace.py
@@ -1,7 +1,65 @@
 """
-Replace a pattern from a message you're about to send, by the result of a
-function.  For example you can insert the current time in your sentence by
-writing %time% in it.
+Replace some patterns in a message before sending it.
+
+
+Installation
+------------
+You only have to load the plugin.
+
+.. code-block:: none
+
+    /load replace
+
+Usage
+-----
+Insert a pattern in the form
+
+.. code-block:: none
+
+    %pattern%
+
+in your message, and it will be replaced by the corresponding text.
+
+The list of provided patterns is:
+
+- **time**: Insert the current time
+- **date**: Insert the current date
+- **datetime**: Insert the current date and time
+- **random_nick**: Insert a random nick from the current MUC
+- **dice**: Insert a random number between 1 and 6
+
+Add your own pattern
+--------------------
+
+You can easily edit this plugin to add your own patterns. For example if
+don’t want to search for an insult everytime you’re angry, you can create a
+curse pattern this way:
+
+- In the init(self) method of the Plugin class, add something like
+
+.. code-block:: python
+
+        self.patterns['curse'] = replace_curse
+
+- then define a function (not a method of the Plugin class) at the bottom
+  of the file. For example:
+
+
+.. code-block:: python
+
+    def replace_curse(message, tab):
+        return random.choice(['dumb shit', 'idiot', 'moron'])
+
+and you can now use something like
+
+.. code-block:: none
+
+    Shut up, %curse%!
+
+in your everyday-conversations.
+
+For more convenience, you can read your nice words from a file, do whatever
+you want in that function, as long as it returns a string.
 """
 
 from plugin import BasePlugin
diff --git a/plugins/revstr.py b/plugins/revstr.py
index 27141969..4d5720dc 100644
--- a/plugins/revstr.py
+++ b/plugins/revstr.py
@@ -1,3 +1,17 @@
+"""
+Reverse everything you say.
+
+Installation
+------------
+
+You only have to load the plugin:
+
+.. code-block:: none
+
+    /load revstr
+
+
+"""
 from plugin import BasePlugin
 
 class Plugin(BasePlugin):
diff --git a/plugins/screen_detach.py b/plugins/screen_detach.py
index 6ee96896..2cc55cd6 100644
--- a/plugins/screen_detach.py
+++ b/plugins/screen_detach.py
@@ -1,3 +1,15 @@
+"""
+This plugin will set your status to **away** if you detach your screen.
+
+Installation
+------------
+You only have to load the plugin.
+
+.. code-block:: none
+
+    /load screen_detach
+
+"""
 from plugin import BasePlugin
 import os
 import stat
diff --git a/plugins/shuffle.py b/plugins/shuffle.py
index edf13083..55f5cad2 100644
--- a/plugins/shuffle.py
+++ b/plugins/shuffle.py
@@ -1,3 +1,17 @@
+"""
+Shuffle the words in every message you send in a :ref:`muctab`
+(may confuse the reader).
+
+Installation
+------------
+
+You only have to load the plugin:
+
+.. code-block:: none
+
+    /load shuffle
+
+"""
 from plugin import BasePlugin
 from random import shuffle
 
diff --git a/plugins/simple_notify.py b/plugins/simple_notify.py
index 62b1f81a..a44a6902 100644
--- a/plugins/simple_notify.py
+++ b/plugins/simple_notify.py
@@ -1,3 +1,69 @@
+"""
+This plugin lets you execute a command, to notify you from new important
+messages.
+
+Installation and configuration
+------------------------------
+
+You need to create a plugin configuration file. Create a file named :file:`simple_notify.cfg`
+into your plugins configuration directory (:file:`~/.config/poezio/plugins` by
+default), and fill it like this:
+
+First example:
+
+.. code-block:: ini
+
+    [simple_notify]
+    command = notify-send -i /path/to/poezio/data/poezio_80.png "New message from %(from)s" "%(body)s"
+
+Second example:
+
+.. code-block:: ini
+
+    [simple_notify]
+    command = echo \\<%{from}s\\> %{body}s >> some.fifo
+    delay = 3
+    after_command = echo >> some.fifo
+
+You can put any command, instead of these ones. You can also use the
+special keywords ``%(from)s`` and ``%(body)s`` that will be replaced
+directly in the command line by the author of the message, and the body.
+
+The first example shown above will display something like this:
+
+.. figure:: ../images/simple_notify_example.png
+    :alt: Simple notify example
+
+The second example will first write the author and the message in a
+fifo, that fifo can locally be read by some other program (was tested
+with the xmobar PipeReader command, which displays what is read from a
+fifo into a status bar. Be careful, you have two different fifos in
+that case, don’t get confused). The :term:`delay` and :term:`after_command` options
+are used to erase/delete/kill the notification after a certain
+delay.  In our example it is used to display an empty message in our
+xmobar, erasing the notification after 3 seconds.
+
+.. note:: If you set the :term:`exec_remote` option to ``true`` into the
+    main configuration file, the command will be executed remotely
+    (as explained in the :ref:`link-plugin` plugin help).
+
+Options defined
+---------------
+
+.. glossary::
+    :sorted:
+
+    command
+        The command to execute (with special keywords ``%{from}s`` and ``${body}s``)
+
+    delay
+        Delay after which :term:`after_command` must be executed.
+
+    after_command
+        Command to run after :term:`delay`. You probably want to clean up things.
+
+"""
+
 from plugin import BasePlugin
 from xhtml import clean_text, get_body_from_message_stanza
 from timed_events import DelayedEvent
diff --git a/plugins/status.py b/plugins/status.py
index c3e0aa7b..9926ffc8 100644
--- a/plugins/status.py
+++ b/plugins/status.py
@@ -1,3 +1,38 @@
+"""
+This plugin adds several aliases, to shorten status changes.
+
+Installation
+------------
+You only have to load the plugin.
+
+.. code-block:: none
+
+    /load status
+
+Aliases
+-------
+
+.. glossary::
+    :sorted:
+
+    /afk
+    /away
+        Set your status to ``away``
+
+    /dnd
+    /busy
+        Set your status to ``dnd``
+
+    /available
+        Set your status to ``available``
+
+    /chat
+        Set your status to ``chat``
+
+    /xa
+        Set your status to ``xa``
+
+"""
 from plugin import BasePlugin
 
 class Plugin(BasePlugin):
diff --git a/plugins/time_marker.py b/plugins/time_marker.py
index 2801ff47..b26a6ae7 100644
--- a/plugins/time_marker.py
+++ b/plugins/time_marker.py
@@ -1,5 +1,7 @@
 """
-A plugin that helps you identify the times of a conversation.  For example
+Display the time between two messages.
+
+Helps you identify the times of a conversation.  For example
 if you disable the timestamps, and remove the join/quit notifications in a
 MUC, you can’t really distinguish when a conversation stopped and when a new
 one started, because you don’t have a visual separation between the two.
@@ -9,6 +11,31 @@ passed between two messages, if the time is bigger than X minutes
 (configurable, of course. Default is 15 minutes). This way you know how many time elapsed between
 them, letting you understand more easily what is going on without any visual
 clutter.
+
+Installation
+------------
+
+You only have to load the plugin.
+
+.. code-block:: none
+
+    /load time_marker
+
+Configuration
+-------------
+
+You can configure the minimum delay between two messages, to display the time marker, in seconds. The default is 10 minutes (aka 600 seconds).
+
+.. code-block:: ini
+
+    [time_marker]
+    delay = 600
+
+Usage
+-----
+
+Messages like “2 hours, 25 minutes passed…” are automatically displayed into the converstation. You don’t need to (and can’t) do anything.
+
 """
 
 from plugin import BasePlugin
diff --git a/plugins/uptime.py b/plugins/uptime.py
index cc47b46f..6138063e 100644
--- a/plugins/uptime.py
+++ b/plugins/uptime.py
@@ -1,3 +1,25 @@
+"""
+This plugin retrieves the uptime of a server.
+
+Installation
+------------
+You only have to load the plugin.
+
+.. code-block:: none
+
+    /load uptime
+
+
+Command
+-------
+
+.. glossary::
+
+    /uptime
+        **Usage:** ``/uptime <jid>``
+
+        Retrieve the uptime of the server of ``jid``.
+"""
 from plugin import BasePlugin
 import tabs
 from common import parse_secs_to_str, safeJID