Add initial docs for mailmon

much of which is just stubs for now...

docs/base/config/available/index.rst

@@ -14,3 +14,4 @@ Available Settings
    datasync
    filemon
    bouncer
+   mailmon

docs/base/config/available/mailmon.rst

@@ -0,0 +1,5 @@
+
+Settings for mailmon
+====================
+
+TODO

docs/base/config/paths.rst

@@ -42,6 +42,9 @@ defines the config needed to run filemon and uses a custom logging file.
 ``bouncer.conf`` is meant to be used only by the ``bouncer`` commands; it
 defines the config needed to run bouncer and uses a custom logging file.
 
+``mailmon.conf`` is meant to be used only by the ``mailmon`` commands; it
+defines the config needed to run mailmon and uses a custom logging file.
+
 
 Machine-Wide
 ------------

docs/base/index.rst

@@ -17,5 +17,6 @@ Base Layer
    cron
    supervisor
    filemon
+   mailmon
    upgrades
    handlers/index

docs/base/mailmon.rst

@@ -0,0 +1,44 @@
+
+Mail Monitoring
+===============
+
+Rattail has a basic "Mail Monitoring" (mailmon) service which can
+watch an IMAP folder, and perform actions on any messages which
+appear.  
+
+Note that one of those actions, presumably the last, should be to
+*move* the message into a different IMAP folder, or perhaps delete it
+outright.  This is to avoid re-processing the same message over and
+over.  The IMAP folder being watched is essentially treated as a
+"queue" and everything in it will be processed.
+
+Example config for this looks something like (in ``mailmon.conf``):
+
+.. code-block:: ini
+
+   [rattail.mailmon]
+   monitor = myfolder
+
+   myfolder.imap.server = mail.example.com
+   myfolder.imap.username = myuser
+   myfolder.imap.password = mypass
+   myfolder.imap.folder = INBOX.Incoming-Messages
+   myfolder.actions = download, move
+   myfolder.action.download.func = rattail.mailmon.actions:download_message
+   myfolder.action.download.args = /srv/envs/poser/app/work/mailmon/myfolder
+   myfolder.action.download.kwarg.locking = true
+   myfolder.action.move.func = rattail.mailmon.actions:move_message
+   myfolder.action.move.args = INBOX.Processed-Messages
+
+In the above example we are watching the "Incoming-Messages" folder,
+which is a subfolder of the INBOX itself.  Any messages which appear
+there will be downloaded to local file system, and then moved to the
+"Processed-Messages" IMAP folder on the server.
+
+Running the command is usually done via supervisor (so as to make it
+behave as a proper service), but the command line itself looks like:
+
+.. code-block:: sh
+
+   cd /srv/envs/poser
+   sudo -u rattail bin/rattail -c app/mailmon.conf mailmon start