added documentation about sending email to askbot

5 files changed, 92 insertions, 17 deletions

diff --git a/askbot/conf/email.py b/askbot/conf/email.py
index b86b7330..953aac3d 100644
--- a/askbot/conf/email.py
+++ b/askbot/conf/email.py
@@ -63,7 +63,8 @@ settings.register(
         help_text = _(
             'NOTE: in order to use this feature, it is necessary to '
             'run the management command "send_unanswered_question_reminders" '
-            '(for example, via a cron job - with an appropriate frequency)'
+            '(for example, via a cron job - with an appropriate frequency) '
+            'and an IMAP server with a dedicated inbox must be configured '
         )
     )
 )
diff --git a/askbot/doc/source/index.rst b/askbot/doc/source/index.rst
index a7fb8122..19d94c26 100644
--- a/askbot/doc/source/index.rst
+++ b/askbot/doc/source/index.rst
@@ -21,6 +21,7 @@ at the forum_ or by email at admin@askbot.org
    Deploy on a webserver <deployment>
    Import data (StackExchange) <import-data>
    Appendix A: Maintenance procedures <management-commands>
+   Appendix B: Sending email to askbot <sending-email-to-askbot>
    Contributors <contributors>
 
 Some background information: Askbot is written in Python on top of the Django platform.
diff --git a/askbot/doc/source/live-settings.rst b/askbot/doc/source/live-settings.rst
new file mode 100644
index 00000000..e154a257
--- /dev/null
+++ b/askbot/doc/source/live-settings.rst
@@ -0,0 +1,21 @@
+.. _live-settings:
+=============
+Live settings
+=============
+
+Many of the configuration settings in askbot are accessible
+to the site administators via link "settings" in the site header.
+
+Any change to the "live settings" will be reflected on the site
+immediately.
+
+No-one but the site administrators can change those settings.
+
+.. note::
+    Any user can be turned into an administrator via running a command.
+
+        python manage.py add_admin <user_id>
+
+    At the moment this command is not available from the web-interface
+    but this will be fixed in the future.
+
diff --git a/askbot/doc/source/management-commands.rst b/askbot/doc/source/management-commands.rst
index 188654bf..a91c0286 100644
--- a/askbot/doc/source/management-commands.rst
+++ b/askbot/doc/source/management-commands.rst
@@ -73,22 +73,41 @@ The bulk of the management commands fall into this group and will probably be th
 |                                 | marked as deleted.                                          |
 +---------------------------------+-------------------------------------------------------------+
 
-Batch jobs
-==========
-
-Batch jobs are those that should be run periodically. A program called `cron` can run these commands at the specified times (please look up futher information about `cron` elsewhere).
-
-+----------------------+-------------------------------------------------------------+
-| command              | purpose                                                     |
-+======================+=============================================================+
-| `send_email_alerts`  | Dispatches email alerts to the users according to           |
-|                      | their subscription settings. This command does not          |
-|                      | send iinstant" alerts because those are sent automatically  |
-|                      | and do not require a separate command.                      |
-|                      | The most frequent alert setting that can be served by this  |
-|                      | command is "daily", therefore running `send_email_alerts`   |
-|                      | more than twice a day is not necessary.                     |
-+----------------------+-------------------------------------------------------------+
+.. _email-related-commands:
+
+Email-related commands
+======================
+
+These commands deal with the periodic tasks related to sending and receiving email by askbot.
+A UNIX program called `cron` can run these commands at the specified times
+(please look up futher information about `cron` elsewhere).
+
+Any configurable options, related to these commands are accessible via "Email" section of the
+:ref:`live settings <live-settings>`.
+
++-------------------------------------+-------------------------------------------------------------+
+| command                             | purpose                                                     |
++=====================================+=============================================================+
+| `send_email_alerts`                 | Dispatches email alerts to the users according to           |
+|                                     | their subscription settings. This command does not          |
+|                                     | send instant" alerts because those are sent automatically   |
+|                                     | and do not require a separate command.                      |
+|                                     | The most frequent alert setting that can be served by this  |
+|                                     | command is "daily", therefore running `send_email_alerts`   |
+|                                     | more than twice a day is not necessary.                     |
++-------------------------------------+-------------------------------------------------------------+
+| `post_emailed_questions`            | (experimental feature) posts questions sent by email        |
+|                                     | to enable this feature - please follow the instructions     |
+|                                     | on :doc:`sending email to askbot <sending-email-to-askbot>`.|
+|                                     | This command uses :ref:`live settings <live-settings>`      |
+|                                     | "allow posting by email" and "replace spaces in tags        |
+|                                     | with dash".                                                 |
++-------------------------------------+-------------------------------------------------------------+
+| `send_unanswered_question_reminders`| Sends periodic reminders about unanswered questions.        |
+|                                     | This command may be disabled from the "email" section       |
+|                                     | of :ref:`live settings <live-settings>`, as well as         |
+|                                     | an initial wait period and the recurrence delay may be set. |
++-------------------------------------+-------------------------------------------------------------+
 
 Data repair commands
 ====================
diff --git a/askbot/doc/source/sending-email-to-askbot.rst b/askbot/doc/source/sending-email-to-askbot.rst
new file mode 100644
index 00000000..b50b8c8e
--- /dev/null
+++ b/askbot/doc/source/sending-email-to-askbot.rst
@@ -0,0 +1,33 @@
+=======================
+Sending email to askbot
+=======================
+
+Askbot supports asking questions by email via the IMAP protocol,
+answering by email is not yet supported.
+
+.. note::
+    This feature is still experimental and some emails will not
+    be parsed, please report any issues at the askbot forum.
+
+To enable the feature, please:
+
+* set up an IMAP mailbox called "INBOX"
+* in your ``settings.py`` file fill out values
+  ``IMAP_HOST``, ``IMAP_HOST_USER``, ``IMAP_HOST_PASSWORD``,
+  ``IMAP_PORT`` and ``IMAP_USE_TLS``
+* in the site :ref:`live settings <live-settings>`, enable the 
+  feature
+* set up a cron job to periodically run command
+  :ref:`post_emailed_questions <email-related-commands>`.
+  This command will connect to the inbox, and post questions,
+  based on the incoming messages.
+
+The email address to send the questions will be
+``<IMAP_HOST_USER>@<IMAP_HOST>``. Also, there is a quite strict
+requirement to the format of incoming messages - described
+in a response to any incorrectly formatted emails.
+
+.. warning::
+    the "INBOX" used to post messages to askbot must be dedicated
+    do not use any other mailbox as all messages
+    are **automatically deleted** after each processing.