Overhaul docs for Windows filemon install

sheesh, hopefully this is "most" of it..although definitely still not
all we need yet..

docs/base/install/windows/filemon/config/basic.rst

@@ -0,0 +1,198 @@
+
+.. highlight:: ini
+
+===========================
+ Basic, aka. "Starter Kit"
+===========================
+
+The purpose of this section is to provide you with a *simple*
+configuration which should be more or less guaranteed to work out of
+the box.
+
+It is suggested that you use this as-is when first installing, in
+order to rule out any "esoteric" issues that can arise from more
+complicated setups.  Once you have this working you can further
+complicate as needed.
+
+
+Config Folder
+-------------
+
+First things first, we need a place for config to live.  As mentioned
+in :doc:`overview` the filemon will only look in one place, so we must
+create this folder: ``C:\ProgramData\rattail``
+
+Note that ``C:\ProgramData`` is a hidden folder, so you may need to
+tweak options in Windows Explorer to see it.
+
+Note that the ``rattail`` user (or whoever the service runs as; see
+:doc:`/base/install/windows/user`) will definitely need "read" access
+to the folder you just created.  It probably has it by default but is
+worth a double-check.
+
+
+Log Folder
+----------
+
+Once we get the filemon running, we should expect it to write a log
+file.  So create the folder for that:  ``C:\ProgramData\rattail\log``
+
+Note that the ``rattail`` user will need read *and* write access to
+that folder; you may need to grant the latter.
+
+
+Testing Folders
+---------------
+
+Before we add our config files let's setup some folders which we will
+(eventually) test actual filemon behavior with.
+
+The basic config will tell filemon to do the following:
+
+* watch ``C:\rattail-test\incoming`` for new files
+* when they appear, move them to ``C:\rattail-test\incoming\processed``
+
+So create the folders:
+
+* ``C:\rattail-test\incoming``
+* ``C:\rattail-test\incoming\processed``
+
+And make sure the ``rattail`` user has read *and* write access to
+them.
+
+
+Config File: ``rattail.conf``
+-----------------------------
+
+This is the "machine-wide" config file (see
+:ref:`machine-wide-config`).  It should contain any "global" things
+which might be useful for any Rattail app running on the machine.
+(Even though in practice you probably only use the filemon app.)
+
+Note that in production it is suggested to use a "site-wide" config
+file which contains most of the global things, so they can be kept in
+just one place (see :doc:`variations`).  But for now we will ignore
+that and just make our ``rattail.conf`` "complete" on its own.
+
+So, create the file ``C:\ProgramData\rattail\rattail.conf`` and in it
+put this, perhaps tweaking timezone if desired but ideally leaving
+everything else as-is::
+
+   ############################################################
+   #
+   # machine-wide rattail config
+   #
+   ############################################################
+
+
+   ##############################
+   # rattail
+   ##############################
+
+   [rattail]
+   timezone.default = America/Chicago
+
+   [rattail.config]
+   configure_logging = true
+   winsvc.RattailFileMonitor = C:\ProgramData\rattail\filemon.conf
+
+
+   ##############################
+   # logging
+   ##############################
+
+   [loggers]
+   keys = root
+
+   [handlers]
+   keys = file, console
+
+   [formatters]
+   keys = generic, console
+
+   [logger_root]
+   handlers = file, console
+   level = DEBUG
+
+   [handler_file]
+   class = handlers.RotatingFileHandler
+   args = (r'C:\ProgramData\rattail\log\rattail.log', 'a', 1000000, 20, 'utf_8')
+   formatter = generic
+
+   [handler_console]
+   class = StreamHandler
+   args = (sys.stderr,)
+   formatter = console
+
+   [formatter_generic]
+   format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(funcName)s: %(message)s
+   datefmt = %Y-%m-%d %H:%M:%S
+
+   [formatter_console]
+   format = %(levelname)-5.5s [%(name)s][%(threadName)s] %(funcName)s: %(message)s
+
+Of course the ``rattail`` user must have read access to this file, so
+you might double-check that.
+
+
+Config File: ``filemon.conf``
+-----------------------------
+
+We will give the filemon service its own config file
+(``filemon.conf``), to avoid cluttering the machine-wide
+``rattail.conf`` file etc.
+
+So, create the file ``C:\ProgramData\rattail\filemon.conf`` and in it
+put this::
+
+   ############################################################
+   #
+   # filemon config
+   #
+   ############################################################
+
+
+   ##############################
+   # rattail
+   ##############################
+
+   [rattail.config]
+   include = C:\ProgramData\rattail\rattail.conf
+
+   [rattail.filemon]
+   monitor = incoming
+
+   incoming.dirs = C:\rattail-test\incoming
+   incoming.actions = copy, delete
+   incoming.action.copy.func = rattail.files:locking_copy
+   incoming.action.copy.args = C:\rattail-test\incoming\processed
+   incoming.action.delete.func = os:remove
+
+
+   ##############################
+   # logging
+   ##############################
+
+   [handler_file]
+   args = (r'C:\ProgramData\rattail\log\filemon.log', 'a', 1000000, 20, 'utf_8')
+
+Again you might make sure the ``rattail`` user has read access to the
+file.
+
+
+Testing the Setup
+-----------------
+
+Once all the above is in place, your basic configuration is complete,
+and you can move on to registering and starting the service; see
+:doc:`/base/install/windows/filemon/register` and
+:doc:`/base/install/windows/filemon/start`.
+
+If the service is working properly then you should be able to put a
+file in the ``C:\rattail-test\incoming`` folder, and filemon should
+immediately "move" it to ``C:\rattail-test\incoming\processed``
+(actually it copies the file, then deletes original, though it could
+be configured to truly move instead).
+
+The service should log its operations to file, at
+``C:\ProgramData\rattail\log\filemon.log``

docs/base/install/windows/filemon/config/index.rst

@@ -0,0 +1,20 @@
+
+===============
+ Configuration
+===============
+
+As usual "the devil is in the details" when it comes to configuration.
+
+The first point we should make is that there are many ways to go about
+this.  Some different approaches are listed a bit later on.
+
+But for starters we want to use a "safe" approach which is more likely
+to work out of the box.  So that will be described first.
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents:
+
+   overview
+   basic
+   variations

docs/base/install/windows/filemon/config/overview.rst

@@ -0,0 +1,33 @@
+
+.. highlight:: ini
+
+==========
+ Overview
+==========
+
+For more general background on Rattail config, see
+:doc:`/base/config/index`.
+
+While it is possible to store config in a DB (see
+:doc:`/base/config/db`), we will not address that here.  All config is
+presumed to exist in files, at least from the perspective of the
+Rattail File Monitor service.  As a rule we avoid DB interactions in
+the filemon to keep its operation as simple as possible.  (Everything
+"interesting" happens on the Linux server.)
+
+The filemon service uses the Windows API to obtain the "default"
+location of the config file.  It is not possible to directly tell the
+service which config file to use, it always will read the default
+path, which is: ``C:\ProgramData\rattail\rattail.conf``
+
+However we still want it to read ``filemon.conf`` instead of
+``rattail.conf`` - and that is possible by way of a special config
+entry within ``rattail.conf``::
+
+   [rattail.config]
+   winsvc.RattailFileMonitor = C:\ProgramData\rattail\filemon.conf
+
+So really when the service starts it first reads ``rattail.conf``, but
+sees that special entry and then reads ``filemon.conf`` *instead*.
+End result is as if it just read ``filemon.conf`` to begin with.  (See
+:doc:`/base/config/inheritance` for more on how some of that works.)

docs/base/install/windows/filemon/config/variations.rst

@@ -0,0 +1,35 @@
+
+.. highlight:: ini
+
+==================
+ Other Approaches
+==================
+
+Here are some variations on the config theme which you may find
+useful.
+
+
+Leveraging Site-Wide Config
+===========================
+
+It is possible to maintain a single "site-wide" config file, which
+your "machine-wide" config inherits from (see :ref:`site-wide-config`
+and :ref:`config-inheritance`).
+
+If you do this, it usually means that your Linux server is running
+Samba and exposing a share which includes the site-wide config
+file(s).  We will assume that scenario here, but we assume that part
+is already setup - it will not be described.
+
+So let's assume then that you have a Linux server named
+``poser-server`` and it exposes a ``rattail`` share, with a ``config``
+folder and ``site.conf`` within that.  So then in your machine-wide
+config on the Windows side, you include it by adding this to
+``C:\ProgramData\rattail\rattail.conf``::
+
+   [rattail.config]
+   include = \\poser-server\rattail\config\site.conf
+
+If you do this then you can also *remove* (most) anything from your
+machine-wide config file, which is also defined in the site-wide
+config file.