Start the plugin documentation

(with admin.py)

5 files changed, 223 insertions, 0 deletions

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 265d5482..28ebe910 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -16,6 +16,7 @@ import sys, os, time
 
 sys.path.insert(0, os.path.abspath('../stub'))
 sys.path.append(os.path.abspath('../../src/'))
+sys.path.append(os.path.abspath('../../plugins/'))
 
 # 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
diff --git a/doc/source/index.rst b/doc/source/index.rst
index aaaff96b..f1eff613 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -16,6 +16,7 @@ Poezio documentation
     keys
     misc/index
     themes
+    plugins/index
     dev/index
 
 ..
diff --git a/doc/source/plugins/admin.rst b/doc/source/plugins/admin.rst
new file mode 100644
index 00000000..fc5875b4
--- /dev/null
+++ b/doc/source/plugins/admin.rst
@@ -0,0 +1,7 @@
+.. _admin-plugin:
+
+Room administration plugin
+==========================
+
+
+.. automodule:: admin
diff --git a/doc/source/plugins/index.rst b/doc/source/plugins/index.rst
new file mode 100644
index 00000000..5af1d7e0
--- /dev/null
+++ b/doc/source/plugins/index.rst
@@ -0,0 +1,154 @@
+Plugins
+=======
+
+Starting from the 0.7.5 version, poezio supports plugins.
+Here is a quick howto and a plugin index.
+
+
+Setting up plugins
+------------------
+
+Poezio seeks the plugins in the :file:`~/.local/share/poezio/plugins/` dir (more
+generally, the :file:`$XDG_DATA_HOME/poezio/plugins/` dir), but that can be changed
+by setting the :term:`plugins_dir` option to the directory where you want to
+put your plugins.
+
+This means that if you want to use a plugin, you have to copy it (the .py file or the directory) into :term:`plugins_dir`.
+
+
+Plugin autoload
+---------------
+
+Use the :term:`plugins_autoload` optionto select which plugins should be
+loaded on startup. The value is a list of plugin names separated by colons,
+e.g.
+
+.. code-block:: ini
+
+    plugins_autoload = gpg:tell:exec
+
+Plugin configuration
+--------------------
+
+Most plugins will manage their configuration internally, and you do not (and
+should not) have to edit it, but some (e.g. mpd_client or gpg) require manual
+editing (the :term:`/set` command can be used, but it is not pleasant to set
+multiple values with it).
+
+The plugin configuration directory is located in :file:`~/.config/poezio/plugins/`
+(or :file:`$XDG_CONFIG_HOME/poezio/plugins/`) and the file related to a specific
+plugin is named :file:`plugin_name.cfg`. The configuration options should usually be
+inside a section named after the plugin (sections are delimited with ``[]``).
+
+.. code-block:: ini
+
+    [plugin_name]
+    key = value
+    other_key = other_value
+
+Plugin index
+------------
+
+.. glossary::
+
+    Admin
+        :ref:`Documentation <admin-plugin>`
+
+        Creates convenient aliases for MUC administration.
+
+    Alias
+
+        Allows you to create your own aliases.
+
+    Amsg
+
+        Allows a message to be broadcasted on all the rooms your are in.
+        Caution: do not overuse.
+
+    Day Change
+
+        Logs the day change inside the buffers, to keep track of the days when
+        backlogging.
+
+    Display corrections
+
+        Lists old versions of a corrected message.
+
+    Exec
+
+        Runs a system command an optionally sends the output as a message.
+
+    Figlet
+
+        Ascii-art writing (requires the ``figlet`` package on your system).
+
+    GPG
+
+        Allows encrypted exchanges and presence signing using GnuPG.
+
+    IQ Show
+
+        Shows the received IQs, for debugging purposes.
+
+    Link
+
+        Opens links in a web browser, locally or remotely using a FIFO and SSH.
+
+    MPD Client
+
+        Sends the current song (and optionally the progress inside the song) to
+        the current (chat) tab.
+
+    OTR
+
+        Allows encrypted and deniable exchanges using OTR.
+
+    PacoKick
+
+        Kicks a random user in the room.
+
+    Ping
+
+        Sends a ping probe to an entity (XEP-0199)
+
+    Quote
+
+        Adds a /quote command to quote a message at HH:MM:SS and put it in the
+        input (to prevent painful copy/pastes).
+
+    Rainbow
+
+        Sends your messages in rainbow colors using XHTML-IM.
+
+    Reminder
+
+        Reminds you to do something every now and then.
+
+    Screen Detach
+
+        Changes your status to _away_ if the screen poezio is in is detached.
+
+    Simple notify
+
+        Sends a notification with a command of your choice on (non-MUC) messages.
+
+    Status
+
+        Adds convenient aliases to /status (/away, etc).
+
+    Tell
+
+        Tells a message to a nick when he connects to a MUC.
+
+    Uptime
+
+        Gets the uptime of a XMPP server or a component.
+
+    Replace
+
+        Replace some patterns in your messages.
+
+    Time Marker
+
+        Display the time between two messages.
+
diff --git a/plugins/admin.py b/plugins/admin.py
index fac34fdb..638a31a6 100644
--- a/plugins/admin.py
+++ b/plugins/admin.py
@@ -1,3 +1,63 @@
+"""
+This plugin adds several convenient aliases, to shorten
+roles/affiliation management.
+
+Installation
+------------
+
+You only have to load the plugin:
+
+``/load admin``
+
+Aliases defined
+---------------
+
+All those commands take a nick or a JID as a parameter.
+
+For roles
+~~~~~~~~~
+
+.. glossary::
+    :sorted:
+
+    /visitor
+    /mute
+        Set the role to ``visitor``
+
+    /participant
+        Set the role to ``participant``
+
+    /moderator
+    /op
+        Set the role to ``moderator``
+
+
+For affiliations
+~~~~~~~~~~~~~~~~
+
+.. glossary::
+    :sorted:
+
+    /admin
+        Set the affiliation to ``admin``
+
+    /member
+    /voice
+        Set the affiliation to ``member``
+
+    /noaffiliation
+        Set the affiliation to ``none``
+
+    /owner
+        Set the affiliation to ``owner``
+
+
+
+
+
+"""
+
+
 from plugin import BasePlugin
 from tabs import MucTab