Move the plugins documentation

(use automodule directive & docstrings)

1 files changed, 104 insertions, 0 deletions

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