README: Start documentation.

ConfigExample.ini

@@ -0,0 +1,39 @@
+[Bot]
+## This section defines configuration the bot uses for its entire
+## connection and runtime.
+
+## jid is required, and where the bot connects to XMPP.
+## If jid does not specify a resource, it will default to "ForwardXMPP".
+# jid = node@example.org/ForwardBot
+
+## password is required.
+# password = ExamplePassword
+
+## nickname is optional. The bot will use this nickname in any MUCs it
+## joins, and on messages it sends. It defaults to the node name in the
+## jid setting above.
+# nickname = FowardBot
+
+## loglevel is optional. Logs will be written to standard error at this
+## level and above. You can specify debug, info, warning, error, or
+## critical. The default is "warning".
+# loglevel = warning
+
+# [Forward example.com messages]
+## Any sections in the configuration file with ``Forward `` at the start of
+## their name define a rule for how messages are forwarded. You can specify
+## as many forwarding rules as you like. You are only limited by the
+## resources available to the bot.
+
+## from is required. Write a Python regular expression to match against the
+## sender's JID. NOTE the regular expression is checked against the *entire*
+## JID, including the resource.
+# from = @example\.com($|/)
+
+## to is required. Messages that match from are sent to this JID.
+# to = example@example.org
+
+## format is optional. Write a Python format string that will be used as the
+## body of the formatted message. Available variables are ``type``, ``body``,
+## ``from``, and ``to``. Refer to the README for full details about each.
+# format = Message from {from.full}: {body}

README.rst

@@ -0,0 +1,61 @@
+ForwardXMPP
+===========
+
+Overview
+--------
+
+FowardXMPP is a bot that connects to an XMPP/Jabber server and forwards messages that it receives. You control what messages it forwards, where it forwards those messages to, and how the forwards are formatted through a simple configuration file.
+
+The configuration file
+----------------------
+
+This package includes a ``ConfigExample.ini`` file that you can use as a basis for your own configuration file. By default ForwardXMPP looks for a configuration file in ``~/.config/forwardxmpp/config.ini``, or if it's run as root, ``/etc/forwardxmpp/config.ini``. You can specify a different configuration file location with the ``--config-file`` switch.
+
+Bot connection
+~~~~~~~~~~~~~~
+
+Settings for the entire bot are configured in a ``[Bot]`` section::
+
+  [Bot]
+  jid = node@example.org/ForwardBot
+  password = ExamplePassword
+  nickname = FowardBot
+  loglevel = warning
+
+``jid`` and ``password`` are the required details for the bot's connection. The bot will use ``nickname`` when it joins MUCs and sends message, if specified.
+
+Logs are written to standard error. The ``loglevel`` setting controls how much is logged. You can specify ``debug``, ``info``, ``warning``, ``error``, or ``critical``.
+
+Forwarding rules
+~~~~~~~~~~~~~~~~
+
+Any sections in the configuration file with ``Forward `` at the start of their name define a rule for how messages are forwarded. Those sections look like this::
+
+  [Forward .com messages to bizdev]
+  from = @example\.com($|/)
+  to = bizdev@example.org
+  format = Message from {from.full}: {body}
+
+You can specify as many forwarding rules as you like. You are only limited by the resources available to the bot.
+
+The ``from`` setting is a `Python regular expression <https://docs.python.org/library/re.html#regular-expression-syntax>`_. When the sender's JID matches this regular expression, the message will be forwarded using the rules in the rest of the section.
+
+**NOTE**: The regular expression is checked against the *entire* JID, including the resource. If you want to check for the end of the domain, use ``($|/)`` as this example, to check for the end of the JID or the beginning of the resource.
+
+The ``to`` setting is a JID where the message is forwarded. It can be a specific user or a MUC. When the bot first connects to a server, it will query all the places it might forward messages, and join any MUCs that are specified.
+
+The ``format`` setting is optional and defines the text of the forwarded message. It is a `Python format string <https://docs.python.org/library/string.html#format-string-syntax>`_ that can use the following variables:
+
+* ``type``: The type of the original XMPP message, i.e., ``chat`` or ``groupchat``.
+* ``body``: The body of the original XMPP message.
+* ``from``: A JID object representing the sender of the original message. You can access the following attributes:
+  * ``from.full``: The sender's entire JID
+  * ``from.bare``: The sender's JID with the resource omitted
+  * ``from.node``: The node of the sender's JID (the part before the @)
+  * ``from.domain``: The domain of the sender's JID
+  * ``from.resource``: The resource of the sender's JID
+* ``to``: A JID object representing the recipient of the original message. Currently this will always belong to the bot. ``to`` has all the same attributes as ``from``.
+
+You can forward the same message(s) to multiple different destinations by
+defining multiple forward rules with the same ``from`` setting and different
+``to`` settings.