From e6cb43eeedcd6c6961c5ab430f25bb962d40bf8e Mon Sep 17 00:00:00 2001 From: mathieui Date: Fri, 12 Apr 2013 23:34:11 +0200 Subject: Start the plugin documentation (with admin.py) --- doc/source/conf.py | 1 + doc/source/index.rst | 1 + doc/source/plugins/admin.rst | 7 ++ doc/source/plugins/index.rst | 154 +++++++++++++++++++++++++++++++++++++++++++ plugins/admin.py | 60 +++++++++++++++++ 5 files changed, 223 insertions(+) create mode 100644 doc/source/plugins/admin.rst create mode 100644 doc/source/plugins/index.rst 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 ` + + 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 -- cgit v1.2.3