Add docs for installation on Windows

docs/base/install/common.rst

@@ -0,0 +1,49 @@
+
+.. highlight:: sh
+
+Common Install Steps
+====================
+
+How exactly you install an app to your virtual environment can vary.
+
+However they all involve using ``pip install`` in some way or another.  And
+therefore your virtual environment should be "activated" when running the
+commands shown below.
+
+
+Installing from PyPI
+--------------------
+
+If the app is published to the `Python Package Index`_ (PyPI) then you can just
+``pip install`` it.  For instance that is the case for `Theo`_, so if that's
+what you're after then::
+
+   pip install tailbone-theo
+
+.. _Python Package Index: https://pypi.org/
+.. _Theo: https://pypi.org/project/tailbone-theo/
+
+
+Installing from Source
+----------------------
+
+If you need (or want) to install from source, then of course the first step is
+to obtain the source code for the app.  Here we'll again use Theo as our example::
+
+   git clone https://kallithea.rattailproject.org/rattail-project/theo
+
+Then you would install that to your virtual environment like so::
+
+   pip install -e ./theo
+
+
+Sanity Check
+------------
+
+Before we do anything else let's confirm that you have the 'rattail' package
+installed, at the very least.  With your env still activated try this::
+
+   rattail --version
+
+That of course should spit out a version number; if you see anything else then
+you may need to troubleshoot that first.

docs/base/install/index.rst

@@ -0,0 +1,18 @@
+
+Installation
+============
+
+How you install depends on the platform you're on, which specific
+app(s) you're installing etc.
+
+At this time only Linux is "officially" supported, for the full
+software suite.  Things *should* work on Windows but the only thing
+"officially" supported on Windows is the Rattail File Monitor service.
+
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents:
+
+   common
+   windows

docs/base/install/windows.rst

@@ -0,0 +1,243 @@
+
+Installing on Windows
+=====================
+
+Here we describe the prerequisites etc. for a Rattail install on Windows.
+
+
+Installing Python
+-----------------
+
+There are surely lots of ways to install Python on Windows, and these
+steps are not necessarily "superior" to other methods, if you know
+what you're doing.  But they do have the benefit of being relatively
+well-tested in production environments.
+
+
+32 bit vs. 64 bit
+~~~~~~~~~~~~~~~~~
+
+In some cases, your Rattail app(s) may need to load and invoke code
+from various compiled libraries.  The most common scenario is that the
+app needs to read data from an ODBC connection which uses a binary
+driver.
+
+Sometimes these libraries are only available in a 32 bit version.  If
+this is the case for you then you must install 32 bit Python, even on
+a 64 bit machine.
+
+.. note::
+   The above statements "used to be true" but it's been a while since
+   I had my head in that game, and much may have changed.
+
+
+Python
+~~~~~~
+
+First of course you'll need Python itself, available at
+`<https://www.python.org/downloads/windows/>`_.
+
+You are encouraged to download the latest version available, although
+in practice older versions will have received more production testing
+in the wild.  At least, it probably should be 3.6 or later.
+
+Remember to watch for the distinction between 32 bit and 64 bit, if
+applicable (see above).
+
+Download the appropriate installer and run it.  If there is an option
+to add Python to your ``PATH`` variable, it's recommended that you do
+so.
+
+At this point you should be able to open a (new!) command line and
+confirm ``python.exe`` is usable:
+
+.. code-block:: none
+
+   C:\>python --version
+   Python 3.7.3
+
+
+If that doesn't work, you may need to manually add e.g.
+``C:\Python37;C:\Python37\Scripts`` to your `PATH environment
+variable`_.
+
+.. _PATH environment variable: http://www.computerhope.com/issues/ch000549.htm
+
+
+Python for Windows Extensions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The situation on Windows is a little more complicated, and the short
+version is that you must also install Mark Hammond's "Python for
+Windows Extensions" package, available at
+`<https://github.com/mhammond/pywin32/releases>`_.
+
+The specific version you download should match the version of Python
+you installed, above.  Again pay attention to 32 bit vs. 64 bit if
+applicable.
+
+Run the installer; all defaults are fine.
+
+
+Pip
+~~~
+
+If you just downloaded a fresh copy of Python (above), then you should
+already have a copy of pip.  If you are working with an older install
+of Python etc. it is possible that you may not yet have pip.  Open a
+command line to find out:
+
+.. code-block:: none
+
+   C:\>pip --version
+   pip 21.1.3 from C:\Python37\lib\site-packages (python 3.7)
+
+If that doesn't work (but ``python --version`` does) then you probably
+need to install pip.  The recommended method is via the ``get-pip.py``
+script according to `these instructions`_.
+
+.. _these instructions: https://pip.pypa.io/en/latest/installing.html#install-pip
+
+
+Installing Rattail
+------------------
+
+See :doc:`common` for more background but if you're just after the
+filemon service then you probably only need to do this:
+
+.. code-block:: sh
+
+   pip install rattail
+
+
+File Monitor Setup
+------------------
+
+With the above in place we now can register the filemon as a proper
+Windows service.
+
+But before we do so we should add some basic config files for it.
+This is because the Windows service has a hard-coded place to look for
+config, so the service will fail to start if the config is not there.
+
+
+File Monitor Config
+~~~~~~~~~~~~~~~~~~~
+
+First create a folder at ``C:\ProgramData\rattail``.
+
+Then create a file at ``C:\ProgramData\rattail\rattail.conf`` with
+contents like:
+
+.. code-block:: ini
+
+   ############################################################
+   #
+   # rattail config
+   #
+   ############################################################
+
+
+   ##############################
+   # rattail
+   ##############################
+
+   [rattail]
+   production = true
+
+   [rattail.config]
+   include = \\my-rattail-server\rattail\config\site.conf
+   winsvc.RattailFileMonitor = C:\ProgramData\rattail\filemon.conf
+
+
+   ##############################
+   # logging
+   ##############################
+
+   [handler_file]
+   args = (r'C:\ProgramData\rattail\log\rattail.log', 'a', 1000000, 20, 'utf_8')
+
+
+Then create a file at ``C:\ProgramData\rattail\filemon.conf`` with
+contents like:
+
+.. code-block:: ini
+
+   ############################################################
+   #
+   # filemon config
+   #
+   ############################################################
+
+
+   ##############################
+   # rattail
+   ##############################
+
+   [rattail.config]
+   include = C:\ProgramData\rattail\rattail.conf
+
+   [rattail.filemon]
+   monitor = 
+           first
+           second
+           third
+
+   first.dirs = C:\folders\first
+   first.actions = copy, delete
+   first.action.copy.func = rattail.files:locking_copy
+   first.action.copy.args = \\my-rattail-server\rattail\files\incoming\first
+   first.action.delete.func = os:remove
+
+   second.dirs = C:\folders\second
+   second.actions = copy, delete
+   second.action.copy.func = rattail.files:locking_copy
+   second.action.copy.args = \\my-rattail-server\rattail\files\incoming\second
+   second.action.copy.retry_attempts = 6
+   second.action.copy.retry_delay = 10
+   second.action.delete.func = os:remove
+   second.stop_on_error = true
+
+   third.dirs = C:\folders\third
+   third.watch_locks = true
+   third.actions = custom, backup
+   third.action.custom.func = poser.filemon_actions:my_custom_func
+   third.action.custom.args = foo
+   third.action.backup.func = rattail.files:overwriting_move
+   third.action.backup.args = C:\folders\third\backup
+
+
+   ##############################
+   # logging
+   ##############################
+
+   [handler_file]
+   args = (r'C:\ProgramData\rattail\log\filemon.log', 'a', 1000000, 20, 'utf_8')
+
+
+Registering the Service
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Note that this must be done in an Administrator console!
+
+.. code-block:: sh
+
+   rattail filemon install --auto-start --username rattail
+
+You are encouraged to use ``rattail`` for the username, but any will
+do if you have another preference.
+
+One common pattern is to have a shared site-wide config provided by
+the "real" Rattail server (presumed to be Linux), which is "included"
+by this machine's config.  An example of this is shown above within
+the ``rattail.conf`` file.
+
+The user which the filemon service runs as, must have access to any
+shares provided by other machines, where it needs to read/write files
+etc.
+
+Note that to *unregister* the filemon service, you can do:
+
+.. code-block:: sh
+
+   rattail filemon remove