Add docs for installation on Windows

docs/base/index.rst

@@ -8,7 +8,7 @@ Base Layer
 
    reqs
    venv
-   install
+   install/index
    appdir
    config/index
    commands

docs/base/install/common.rst

@@ -1,8 +1,8 @@
 
 .. highlight:: sh
 
-Installation
+Common Install Steps
-============
+====================
 
 How exactly you install an app to your virtual environment can vary.
 

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

docs/data/batch/custom.rst

@@ -3,8 +3,8 @@
 Adding a Custom Batch
 =====================
 
-If none of the native batch types fit your needs, you can always add a new one.
+If none of the native batch types fit your needs, you can always add a
-See :doc:`native` for the list of what's available.
+new one.  See :doc:`native/index` for the list of what's available.
 
 Adding a new batch type involves 3 steps:
 

docs/data/batch/handlers.rst

@@ -10,7 +10,7 @@ it per user edits, refresh it etc. and ultimately execute it.
 The UI exposes tools for interacting with the batch but ultimately the handler
 is what "acts on" the batch based on user input.
 
-See also :doc:`/base/handlers` for general info on handlers.
+See also :doc:`/base/handlers/index` for general info on handlers.
 
 Each type of batch will have precisely one "handler" associated with it.  For
 instance, there is a handler for inventory batches, and another for label