Add basic docs for demo, installation, development

dev/nodb.conf

@@ -0,0 +1,14 @@
+
+############################################################
+#
+# avoid db config (use files only)
+#
+############################################################
+
+
+##############################
+# rattail
+##############################
+
+[rattail.config]
+usedb = false

dev/tasks.py

@@ -162,6 +162,10 @@ def make_configs(c, envdir, appdir, info):
             c.run('{}/bin/rattail make-config -T quiet -O {}'.format(
                 envdir, appdir))
 
+    # nodb.conf
+    if not os.path.exists(os.path.join(appdir, 'nodb.conf')):
+        shutil.copyfile('nodb.conf', os.path.join(appdir, 'nodb.conf'))
+
     # web.conf
     if not os.path.exists(os.path.join(appdir, 'web.conf')):
         with open('web.conf') as f:
@@ -177,11 +181,12 @@ def check_db(c, envdir, appdir):
     Do basic sanity checks for Theo database
     """
     if sys.platform == 'win32':
-        c.run('{} -c {} --no-versioning checkdb'.format(
-              os.path.join(envdir, 'Scripts', 'rattail'),
-              os.path.join(appdir, 'quiet.conf')))
+        c.run('{} -c {} -c {} --no-versioning checkdb'.format(
+            os.path.join(envdir, 'Scripts', 'rattail'),
+            os.path.join(appdir, 'quiet.conf'),
+            os.path.join(appdir, 'nodb.conf')))
     else:
-        c.run('{}/bin/rattail -c {}/quiet.conf --no-versioning checkdb'.format(
+        c.run('{0}/bin/rattail -c {1}/quiet.conf -c {1}/nodb.conf --no-versioning checkdb'.format(
             envdir, appdir))
 
 

docs/conf.py

@@ -36,8 +36,13 @@ release = '0.1.x'
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinx.ext.intersphinx',
 ]
 
+intersphinx_mapping = {
+    'rattail-manual': ('https://rattailproject.org/docs/rattail-manual/', None),
+}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

docs/demo.rst

@@ -0,0 +1,15 @@
+
+Online Demo
+===========
+
+There is an online demo for Theo at https://demo-theo.rattailproject.org/
+
+You can login with credentials:
+
+* username: chuck
+* passowrd: admin
+
+This demo integrates with CORE-POS (also a demo) which contains some
+sample data.  The data isn't great but should prove the concepts.
+
+The CORE Office demo may be viewed at https://demo-fannie.rattailproject.org/

docs/develop.rst

@@ -0,0 +1,23 @@
+
+Development
+===========
+
+Theo by nature is just a "wrapper" project, and as such does not
+change terribly often.  The underlying packages contain all the "good
+stuff" and they change more frequently.
+
+Rattail and Tailbone are the 2 main packages, responsible for the
+"core" data layer, and web layer, respectively.
+
+Usually there are also some POS integration packages involved; see
+:ref:`pos-integration` for links to those.
+
+Source code for *all* packages is hosted on the rattailproject.org
+server, specifically under https://kallithea.rattailproject.org/
+
+You can request an account there, and then "fork" anything as you
+like.  Or skip the account and just clone whatever.  
+
+Note that certain POS integration packages are "restricted" and not
+available as part of the public project.  If you need access then
+please send a request.

docs/features.rst

@@ -56,6 +56,8 @@ nothing more will happen to it.  They are of course kept intact for
 reporting etc.
 
 
+.. _pos-integration:
+
 POS Integration
 ---------------
 

docs/index.rst

@@ -23,11 +23,14 @@ Please see `https://rattailproject.org/docs/theo/
 document.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
    :caption: Contents:
 
    quickstart
    features
+   demo
+   install/index
+   develop
 
 
 Indices and tables

docs/install/fabric.rst

@@ -0,0 +1,7 @@
+
+Installing with Fabric
+======================
+
+TODO
+
+For now please see https://rattailproject.org/moin/Theo/ServerSetup

docs/install/index.rst

@@ -0,0 +1,14 @@
+
+Installation
+============
+
+There are a few ways to go about installing Theo, which we'll describe
+here.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   manual
+   fabric
+   integration

docs/install/integration.rst

@@ -0,0 +1,130 @@
+
+.. highlight:: ini
+
+Integrating the POS
+===================
+
+The general process of integrating a POS is roughly the same (so far)
+regardless of which POS system is involved.  Here we describe the
+setup etc.
+
+We will use CORE-POS as our example, for a few reasons, not least of
+which is that it's also free (libre) software.  See
+:ref:`pos-integration` for links to others.
+
+
+Install Packages
+----------------
+
+Please remember to activate your virtual environment.
+
+The first thing is, you must install the POS integration packages.
+The packages for CORE-POS are publiclly available, in which case if
+you just want the latest releases:
+
+.. code-block:: sh
+
+   pip install tailbone-theo[app,corepos]
+
+Or if you want to run from source then you can clone/install these:
+
+* https://kallithea.rattailproject.org/rattail-project/pycorepos
+* https://kallithea.rattailproject.org/rattail-project/rattail-corepos
+* https://kallithea.rattailproject.org/rattail-project/tailbone-corepos
+
+But then just in case, do also run the above command as well, to
+ensure all dependencies are got.
+
+
+Modify Config
+-------------
+
+You must tell Alembic how to find all schema extensions for your POS
+integration package.  Modify ``/srv/envs/theo/app/rattail.conf`` per
+the following.
+
+The default contains::
+
+   [alembic]
+   version_locations = rattail.db:alembic/versions
+
+But you now instead need something like::
+
+   [alembic]
+   version_locations = rattail_corepos.db:alembic/versions rattail.db:alembic/versions
+
+Note that the POS integration path should come before the default path
+there.
+
+In the same config file, you should declare your integration to Theo::
+
+   [theo]
+   integrate_corepos = true
+
+
+Migrate Database
+----------------
+
+Most integrations will require some extra tables installed to your
+database.  But installing them is no different than any other
+migration, i.e. just run the normal commands:
+
+.. code-block::sh
+
+   cd /srv/envs/theo
+   bin/alembic -c app/rattail.conf upgrade heads
+
+
+Import POS Data
+---------------
+
+This process can vary a little but a couple of concepts will be useful
+regardless.
+
+First is that data "versioning" must be considered here.  Theo
+normally will use the versioning feature, i.e. whenever a record
+changes, a new "version" record is also created for it.  The logic
+behind this has some performance cost, which is by far most pronounced
+when there are a "lot" of changes within the same database session.
+
+Therefore a workaround is employed when the database is initially
+populated: the versioning feature is disabled for the main import, and
+then version records are created for the initial data in a separate
+step.  So the first import command always includes ``--no-versiong``:
+
+.. code-block:: sh
+
+   cd /srv/envs/theo
+   bin/rattail -c app/quiet.conf -P import-corepos-api --no-versioning
+
+Once all the data lives in Theo, then capture the initial version
+records for everything.
+
+.. code-block:: sh
+
+   bin/rattail -c app/quiet.conf -P --runas corepos import-versions -m "initial data from POS"
+
+Note the ``--runas`` arg above, which declares the Theo username
+responsible.  The user must already exist within Theo, but can be
+created via the Theo web app.
+
+
+Ongoing Sync
+------------
+
+There are a few ways to do the ongoing "sync" between the POS system
+and Theo.  For now we will only describe a very basic sync which
+happens once per night, although could also be used hourly etc.
+
+The idea here is basically just like the initial data import, although
+should not need the versioning workaround.  So one command, something
+like:
+
+.. code-block:: sh
+
+   cd /srv/envs/theo
+   bin/rattail -c app/quiet.conf --runas corepos import-corepos-api
+
+This is a very basic example, in particular does not handle
+"deletions" which may occur in CORE.  For now though we'll leave it at
+that, hopefully more to come later.

docs/install/manual.rst

@@ -0,0 +1,176 @@
+
+.. highlight:: sh
+
+Installing Manually
+===================
+
+See also :doc:`/quickstart`, as it automates many of the steps below.
+
+More general details and background may be found in the Rattail
+Manual; see :doc:`rattail-manual:base/index` for that.  Here of course
+we will focus on Theo, so will be less generic.
+
+The initial setup below will *not* include any POS integration, but
+that may optionally be added, and is described in another section.
+
+
+Prerequisites
+-------------
+
+* Python 3.6+
+* PostgreSQL
+
+Note that PostgreSQL need not run on the same machine as the Theo app,
+it just needs to be accessible over the network by Theo.
+
+These docs assume Linux for the Theo machine, but it is believed that
+with minimal tweaks this should work on Windows as well.  However it
+should be noted that Windows does pose some issues, and this all
+likely will work "better" on Linux at this point.  Windows "support"
+should be considered experimental.
+
+(In any case PostgreSQL can run on a Windows machine if you prefer
+that.)
+
+
+Virtual Environment
+-------------------
+
+These docs will assume ``/srv/envs`` for the "home folder" of your
+virtual environments.
+
+Create a virtual environment for Theo::
+
+   mkdir -p /srv/envs
+   python3 -m venv /srv/envs/theo
+
+Now activate it with::
+
+   source /srv/envs/theo/bin/activate
+
+Remember you can deactivate the virtual environment with::
+
+   deactivate
+
+But your environment should be *active* for all commands below.
+
+
+Install Packages
+----------------
+
+In a production environment you probably would want to install
+"official" released packages for Theo etc.  That can be done for
+instance like::
+
+   pip install tailbone-theo[app]
+
+That is just an example and would not install any POS integration
+packages, only Theo proper.
+
+However in practice you may want to clone the source packages and
+install those in "editable" mode instead.  In a true development
+environment we would suggest keeping the source code *outside* of the
+virtual environment, so that is what we'll describe here.
+
+First make and/or move to the parent folder for your source code,
+e.g.::
+
+   mkdir -p ~/src
+   cd ~/src
+
+Then clone any packages you don't yet have, e.g.::
+
+   git clone https://kallithea.rattailproject.org/rattail-project/rattail
+   git clone https://kallithea.rattailproject.org/rattail-project/tailbone
+   git clone https://kallithea.rattailproject.org/rattail-project/theo
+
+Finally install all packages to your virtual environment, e.g.::
+
+   pip install -e ~/src/rattail
+   pip install -e ~/src/tailbone
+   pip install -e ~/src/theo
+
+But just to be sure no dependencies are missed, you still should run
+the same command as would be used in production, e.g.::
+
+   pip install tailbone-theo[app]
+
+Note that this command should always be ran *last* after you have
+installed all your source packages.
+
+
+Make Config Files
+-----------------
+
+The ``dev/bootstrap.py`` script referenced by :doc:`/quickstart` will
+install four different config files, but we'll only install three
+here.
+
+First create the "app" folder (will be at ``/srv/envs/theo/app``)::
+
+   cd /srv/envs/theo
+   bin/rattail make-appdir
+
+One of the config files is quite simple and can be copied "as-is" from
+elsewhere, but two of them will require some modification depending on
+your setup etc.  Starting point examples are available for the latter
+two, but cannot be used "as-is" due to their nature.
+
+Note that all config files will go directly in the "app" folder we
+just made above.
+
+We'll do the more complicated ones first.  You can grab copies of them
+from Theo source code:
+
+* `rattail.conf <https://kallithea.rattailproject.org/rattail-project/theo/rawfile/master/dev/rattail.conf>`_
+* `web.conf <https://kallithea.rattailproject.org/rattail-project/theo/rawfile/master/dev/web.conf>`_
+
+Put each copy in your Theo "app" folder and edit as needed, in
+particular replacing ``<ENVDIR>`` and similar strings (e.g. ``<SEP>``
+should be either ``/`` on Linux or ``\`` on Windows).
+
+And now for the easy one, you can do this::
+
+   cd /srv/envs/theo
+   bin/rattail -c app/rattail.conf make-config -T quiet -O app
+
+
+Initialize Database
+-------------------
+
+On your PostgreSQL server, if you haven't already, create the user
+with which Theo should connect.  We suggest "rattail" for the
+username::
+
+   sudo -u postgres createuser -P rattail
+
+Also create the database for Theo::
+
+   sudo -u postgres createdb -O rattail theo
+
+Now back on the Theo server (if different), install the schema to the
+database (NB. this assumes your ``rattail.conf`` file correctly points
+to the PostgreSQL DB)::
+
+   cd /srv/envs/theo
+   bin/alembic -c app/rattail.conf upgrade heads
+
+You also should create your admin user in Theo, named whatever you
+like::
+
+   bin/rattail -c app/quiet.conf make-user myusername --admin --full-name "My Actual Name"
+
+
+Run Web App
+-----------
+
+With all the above in place you can run the web app::
+
+   cd /srv/envs/theo
+   bin/pserve --reload file+ini:app/web.conf
+
+And then browse the app at http://localhost:9080/
+
+Note that this is a basic setup and does not cause the web app to run
+in the background or after reboot etc.  This type of setup is most
+useful for development.

docs/quickstart.rst

@@ -23,9 +23,9 @@ and DB (named ``theo``) created::
 Make and activate a virtual environment, e.g. ``/srv/envs/theo``::
 
    mkdir -p /srv/envs
-   python -m venv /srv/envs/theo
+   python3 -m venv /srv/envs/theo
    source /srv/envs/theo/bin/activate
 
 With the virtual environment active, run the development bootstrap script::
 
-   python ~/src/theo/dev/bootstrap.py
+   python3 ~/src/theo/dev/bootstrap.py