Transfer ad-hoc setup docs to tutorial project

Vagrantfile

@@ -0,0 +1,8 @@
+# -*- mode: ruby; -*-
+
+Vagrant.configure("2") do |config|
+
+  # target machine runs Debian 10 "buster"
+  config.vm.box = "debian/buster64"
+
+end

docs/conf.py

@@ -31,6 +31,7 @@ release = '0.1'
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinx.ext.todo',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -41,6 +42,9 @@ templates_path = ['_templates']
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
+# Allow todo entries to show up.
+todo_include_todos = True
+
 
 # -- Options for HTML output -------------------------------------------------
 

docs/create-project.rst

@@ -0,0 +1,194 @@
+
+.. highlight:: sh
+
+Create a New Project
+====================
+
+Now that you've setup your development environment, you're ready to create a
+new Rattail-based project.
+
+.. todo::
+   link to dev env setup doc here?
+
+Note again that while Rattail is a project in itself, your app is yet another
+project, which is "based" on Rattail but otherwise has a life of its own.  It
+is *not* a "fork" of Rattail but intsead uses Rattail as a library.
+
+Notes About Names
+-----------------
+
+There are some points to be made here, regarding project names.
+
+First point has to do with the "types" of names involved.  Really there are 3:
+
+* "repo" name
+* "project" name
+* "package" name
+
+What we're calling "repo" name here, refers to the so-called "slug" name for
+the repo, e.g. the actual folder name for the repo on disk.
+
+What we're calling "project" name here, refers to the "official" project name,
+e.g. as it might be registered on PyPI or generally referenced in
+documentation, etc.
+
+What we're calling "package" name here, refers to the actual name of the Python
+package contained within the project.
+
+And there technically is a 4th, the "virtualenv" name.  This refers to the
+Python virtual environment you will create, within which you will install your
+project.  This virtualenv name need not be related necessarily, to your project
+name, but in practice it usually would be.  In some cases you may have multiple
+virtualenvs and each must of course get a unique name.
+
+Some examples will surely help.
+
+.. todo::
+   should really have a table instead of lists here?
+
+Example Project: Poser
+
+* repo name: poser
+* project name: Poser
+* package name: poser
+
+Example Project: rattail-tutorial
+
+* repo name: rattail-tutorial
+* project name: rattail-tutorial
+* package name: rattut
+
+Note how the "Poser" name is much more friendly and homogenous as compared to
+the "rattail-tutorial" name, when considering all 3 "types" of names involved.
+Really "rattail-tutorial" is not an example of a good name per se, but it was
+given to this project for other reasons.
+
+This sort of brings us to the second point about names, which is that they
+*should* be "good" generally speaking.  You ideally would want a name more like
+"Poser" in that it's simple and easily recognizable, etc.
+
+.. todo::
+   link to "how to name project" doc
+   (https://rattailproject.org/moin/LilSnippets/ProjectNaming)
+
+Creating the Virtual Environment
+--------------------------------
+
+As mentioned above, the name you give your virtual environment is really up to
+you, and needn't "match" your project name etc.
+
+Let's assume for a moment that you are creating a new project (described next)
+named "Poser" - you likely will want to make a virtualenv named "poser" also::
+
+   mkvirtualenv --python=/usr/bin/python3 poser
+    
+Note that you should specify the path to your Python 3 executable, to avoid
+using the "default" which is likely still Python 2 at this time.
+
+For the sake of this tutorial, we'll be using the "rattut" env name::
+
+   mkvirtualenv --python=/usr/bin/python3 rattut
+    
+Please note that pretty much all subsequent commands shown, will assume your
+virtual environment (regardless what you named it) is currently *active*.  It
+should be obvious when a virtualenv is active, since it should modify the shell
+prompt to reflect that.
+
+If you do need to deactivate your current virtualenv, you can do that with::
+
+   deactivate
+
+And then to re-activate your virtualenv you do::
+
+   workon rattut
+
+Or maybe ``workon poser`` etc., whatever named env you want to activate.
+
+Installing Rattail Packages
+---------------------------
+
+If you're just wanting to run the rattail-tutorial app instead of creating your
+own project, you can skip this step.
+
+But in this tutorial we're showing how to do it all, and so before we can
+create the tutorial project itself we must first install some Rattail packages
+to our virtual environment.  Well really there's just one (Tailbone) which is
+needed because it contains the "rattail" scaffold, and also it depends on other
+packages (namely, Pyramid) which are needed for the scaffold feature::
+
+   pip install Tailbone
+
+Creating the Project
+--------------------
+
+Again if you're just wanting to run the rattail-tutorial app you can skip this
+step.
+
+First of all you should change directory to wherever you want to create the
+actual project source folder.  Rattail docs will generally assume that's at
+``~/src`` in which case you should do something like::
+
+   mkdir -p ~/src
+   cd ~/src
+
+Remember all that talk about names, up above?  Well now you will be specifying
+a *single* name when creating your project.  In practice the name you provide:
+
+* should be lower-cased
+* will be used as-is for the "repo" name
+* will be capitalized (and weird chars replaced) to obtain "project" name
+* will be used as-is for the "package" name, except weird chars replaced by "_"
+
+Got all that straight?  If not, no worries, just try this a few times and see
+what you end up with.  Assuming you did want the project name "Poser" you would
+run the command::
+
+   pcreate -s rattail poser
+
+This will use the "scaffold" (basically, set of templates) which is named
+"rattail" to generate a new folder containing files which define a new "Poser"
+project, within the "poser" folder under current directory.
+
+Since this tutorial project is named "rattail-tutorial" and there's no possible
+way for the scaffold to know that we want to use "rattut" as the Python package
+name, we had to simply "pick our poison" when generating the initial tutorial
+project.  In other words we did::
+
+   pcreate -s rattail rattail-tutorial
+
+Note that per the above rules, what the scaffold assumed by default was:
+
+* repo name was "rattail-tutorial"
+* project name was "Rattail_tutorial"
+* package name was "rattail_tutorial"
+
+We'll clean that up a bit shortly, but first let's start Git tracking.
+
+Making a Git Repo
+-----------------
+
+We never want to start a new project without also starting a proper Git repo
+for it.  We will want to be able to ``git push`` the code to a central
+location, e.g. GitHub or similar.
+
+Change directory to your new project's source repo folder and then initialize::
+
+   cd ~/src/rattail-tutorial
+   git init
+
+We also want our first commit to include all the generated code so far::
+
+   git add .
+   git commit -m "Initial content as generated from project scaffold"
+
+Now we'll establish our upstream and do our first push.  How exactly you go
+about this may vary, and certainly the commands shown here will *not* work for
+you as-is, since your "origin" at least will need to be different::
+
+   git remote add origin git@rattailproject.org:/srv/git/rattail-tutorial.git
+   git push --set-upstream origin master
+
+And finally, at least in the case of this tutorial project, we wanted to go
+through and clean up some of the generated names, as well as assign authorship
+and project description etc. within the ``setup.py`` file.  (Then commit those
+changes and do another push, so we again have "clean" git status.)

docs/index.rst

@@ -1,15 +1,59 @@
-.. rattail-tutorial documentation master file, created by
-   sphinx-quickstart on Fri Aug 16 21:39:33 2019.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
 
-Welcome to rattail-tutorial's documentation!
+Rattail Tutorial
-============================================
+================
+
+First of all, welcome to Rattail!
+
+This project is a tutorial of sorts, to show how to use Rattail in the real
+world.  (It is accordingly named 'rattail-tutorial'.)
+
+While it aims to cover many areas, this tutorial is not exhaustive.  This
+project's goals include:
+
+* show how to setup your development environment
+* show how to create a new project
+* show how to get your project up and running, i.e. with a database and web app
+* show how to customize and extend your app in various ways, to suit your needs
+* show how to integrate with another system (CORE-POS) in a custom way
+* provide a "working example" of all documented concepts
+
+That last one means, you can install and run the rattail-tutorial app yourself,
+and e.g. further customize it to get a feel for Rattail.
+
+Please see `https://rattailproject.org/docs/rattail-tutorial/
+<https://rattailproject.org/docs/rattail-tutorial/>`_ for the latest version of
+this document.
+
+
+Front Matter
+------------
+
+It will be helpful to understand a few things before you get started:
+
+**Rattail itself is a "library" more than it is an "app".** The idea is that the
+Rattail Project will provide "most" of the base functionality you need from an
+app, but ultimately you must create a project of your own, which "uses" Rattail
+functionality to accomplish *your* goals.
+
+**Rattail docs always refer to "your" app with the name "Poser".** In fact this
+tutorial will *not* be using the name "Poser" (much) - but that is usually what
+you will see in all *other* docs, to represent "your" (i.e. any custom) app.
+
+**This "rattail-tutorial" project is a proper app.** Following from the
+previous point, this project/app is named "rattail-tutorial" and therefore
+instead of using the name "Poser" within this tutorial, we will be using its
+*actual* name.
+
+
+Table of Contents
+-----------------
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
 
+   setup-dev
+   create-project
+   start-docs
 
 
 Indices and tables

docs/setup-dev.rst

@@ -0,0 +1,275 @@
+
+.. highlight:: sh
+
+Setup Development Environment
+=============================
+
+These are the main requirements for a development environment, as pertains to
+Rattail:
+
+* Linux (Debian-ish)
+* Git
+* Python (3.x)
+* virtualenvwrapper
+* PostgreSQL
+
+Technically it's possible for you to work around some of these, but not all.
+However this tutorial will assume that all these requirements are met.
+
+Now we'll go through these requirements in more detail, and how to satisfy each
+one.
+
+Linux
+-----
+
+So, the operating system upon which production Rattail software runs, is
+generally assumed to be `Linux`_.  To the author's knowledge, this holds true
+across all existing production installs.
+
+.. _Linux: https://en.wikipedia.org/wiki/Linux
+
+There is technically one exception to this: the Rattail "File Monitor service"
+(which is the Windows equivalent of the Rattail "File Monitor daemon" on Linux)
+of course does run (only) on Windows, and has been used heavily in production.
+But one of its primary tasks is usually just to move files (e.g. which emanate
+from POS system) over to the "real" Rattail server on Linux somewhere.
+
+It is possible that you could run a full Rattail stack on Windows (or MacOS for
+that matter?), e.g. with PostgreSQL database and web app, possibly even
+datasync etc.  However there is no effort put toward supporting that currently,
+so again Linux is assumed here.
+
+Now that we've established Linux, we go a bit further and specify
+"Debian-ish" - in practice the only two distros used so far, are `Debian`_ and
+`Ubuntu`_.  You are encouraged to use a "stable" version here, regardless of
+which distro you prefer.  It's likely other distros would work also, as far as
+just running the app(s); however some of Rattail's "configuration management"
+utilities (use of which is of course optional) are built with Debian/Ubuntu in
+mind.
+
+.. _Debian: https://www.debian.org/
+.. _Ubuntu: https://ubuntu.com/
+
+The "where" question is worth mentioning here too.  In practice a production
+Rattail server can be either a bare-metal machine running on your local
+network, or indeed a "virtual" machine running either locally or in the cloud.
+Whether you run locally or in the cloud usually will depend on other factors,
+e.g. if the app must integrate directly with a POS system then it probably must
+run on the local network.  (And of course you can always run in "both" places,
+with datasync keeping everything flowing smoothly between them.)
+
+Setting It Up
+^^^^^^^^^^^^^
+
+In this tutorial we will be using `Vagrant`_ to spin up a local Debian Linux
+virtual machine (VM) with `VirtualBox`_ as the "provider".  This is primarily
+so we can show an example which you could reproduce on your end, but also one
+which could stay "isolated" and not interfere with any other stuff you may have
+going on.
+
+.. _Vagrant: https://www.vagrantup.com/
+.. _VirtualBox: https://www.virtualbox.org/
+
+First thing then, will be to install VirtualBox and Vagrant if you do not
+already have them.  You must install these to your "bare-metal development"
+machine, i.e. your laptop.
+
+Once those are in place, you can use the ``Vagrantfile`` which comes with this
+(rattail-tutorial) project, to create a new VM.  Note that this VM does not
+come with any special behavior, it's as "vanilla" as possible.
+
+Here is the contents of this ``Vagrantfile`` in case you need to create your
+own, outside of the rattail-tutorial project:
+
+.. literalinclude:: ../Vagrantfile
+   :language: ruby
+
+Change to the directory which contains your ``Vagrantfile`` and then run
+``vagrant up``, e.g.::
+
+   cd ~/src/rattail-tutorial
+   vagrant up
+
+Those commands assume your "host" machine (i.e. your laptop) runs Linux too,
+though of course that may not be so.  Please adjust accordingly.
+
+Confirming It Works
+^^^^^^^^^^^^^^^^^^^
+
+There are really two things you should check, to confirm "all is well"
+regarding your new Linux machine, regardless of whether it's a Vagrant VM, or
+some bare-metal machine.
+
+**Check #1** - Can you open a console terminal for the machine?  If it's
+bare-metal then this probably just means making sure the keyboard and/or mouse
+are working, and you can login.  If it's virtual then this probably means
+making sure you can ssh into it.  (You may want to use ssh even if it's
+bare-metal, depending on its role etc.)
+
+**Check #2** - Are you able to use ``sudo`` for elevated privileges?  If the
+Check #1 passed then you should be able to run e.g. ``sudo whoami`` on the
+terminal.  It's okay to be prompted for a password as long as you know what
+that is. ;) Otherwise this check fails.
+
+Note that if you're using Vagrant, you should be able to do ``vagrant ssh`` in
+order to connect, and from there ``sudo`` should be no problem.
+
+Git
+---
+
+This one's pretty obvious and you may already have it, but we'll cover it
+anyway to be thorough.
+
+Setting It Up
+^^^^^^^^^^^^^
+
+Install with::
+
+   sudo apt install -y git
+
+But we'll also want to define your Git user identity, e.g.::
+
+   git config --global user.name "John Doe"
+   git config --global user.email "john@example.com"
+
+Confirming It Works
+^^^^^^^^^^^^^^^^^^^
+
+This should work as expected::
+
+   git --version
+    
+Also these should output the same values as you defined above::
+
+   git config --global user.name
+   git config --global user.email
+
+Python
+------
+
+Since we're assuming Linux here (e.g. on the Vagrant VM), you probably already
+have Python installed.  However we do want to make sure you have Python 3.x -
+since Python 2 is EOL quite soon as of this writing.
+
+Setting It Up
+^^^^^^^^^^^^^
+
+To make sure you have Python 3.x, run the following command::
+
+   sudo apt install -y python3
+
+Confirming It Works
+^^^^^^^^^^^^^^^^^^^
+
+You should now be able to confirm a Python 3.x binary with this command::
+
+   python3 --version
+
+You probably also should find out where exactly this binary lives::
+
+   which python3
+
+The output from that most likely points to ``/usr/bin/python3`` but please make
+a note of your location if it's different.
+
+Misc. Other Dependencies
+------------------------
+
+These don't really fit any other category, and aren't *necessarily* required,
+depending on your project etc.  But they're often necessary and we might as
+well install them just in case::
+
+   sudo apt install -y build-essential
+
+virtualenvwrapper
+-----------------
+
+The `virtualenvwrapper`_ package is, in this author's opinion, quite useful for
+both Rattail development, as well as production installs.  For this reason,
+this tutorial will assume its presence, even though technically Rattail does
+not require it.
+
+.. _virtualenvwrapper: https://virtualenvwrapper.readthedocs.io/en/latest/
+
+Setting It Up
+^^^^^^^^^^^^^
+
+Before actually installing virtualenvwrapper, let's prep our "workon home"
+directory.  This tutorial assumes, as do all Rattail docs, that the workon home
+resides at ``/srv/envs`` - again you're free to use another location, but all
+docs will assume that one.  These commands should prep the workon home folder
+(adjust path and/or username as needed)::
+
+   sudo mkdir /srv/envs
+   sudo chown you:you /srv/envs
+
+Note that for development it's often convenient to make this folder owned by
+"you" whereas in production installs the author recommends making this folder
+owned by a special "rattail" system user.
+
+Now for virtualenvwrapper itself.  There are technically a few ways to go about
+this, but for the sake of the tutorial we'll just do this::
+
+   sudo apt install -y virtualenvwrapper
+
+Next you must add the following to your ``~/.bashrc`` file::
+
+   export WORKON_HOME=/srv/envs
+   source /usr/share/virtualenvwrapper/virtualenvwrapper.sh
+
+And finally you must "re-run" your ``.bashrc`` so these things actually take
+effect for your current session::
+
+   source ~/.bashrc
+
+Confirming It Works
+^^^^^^^^^^^^^^^^^^^
+
+First of all just to be 100% sure, you ideally should reboot your new machine,
+or perhaps at least logout and then login again.
+
+But really the check here, is to make sure the following command runs okay::
+
+   workon --help
+
+PostgreSQL
+----------
+
+Rattail uses `PostgreSQL`_ exclusively, for its "primary" database backend.  So
+whereas Rattail can interact with many other types of SQL databases, it uses
+Postgres for its "own" database(s).
+
+.. _PostgreSQL: https://www.postgresql.org/
+
+Technically the database is optional, depending on how you need to use Rattail,
+although it is required for the web app.
+
+Setting It Up
+^^^^^^^^^^^^^
+
+There are really two aspects of this setup, a) Postgres proper, and b) Python
+support for Postgres.
+
+We'll tackle the first aspect, well, first::
+
+   sudo apt install -y postgresql
+
+Next we'll tackle the second aspect::
+
+   sudo apt install -y libpq-dev
+
+Confirming It Works
+^^^^^^^^^^^^^^^^^^^
+
+As with the setup for Postgres, there are really two things to check here.
+
+First, is the PostgreSQL service running and available?  You should be able to
+confirm that with (should output list of databases)::
+
+   sudo -u postgres psql -l
+
+Second, is Python support for Postgres installed correctly?
+
+.. todo::
+   what else should we say about the second aspect here?  other than, TBD
+   (aka. "when you need it you'll know")

docs/start-docs.rst

@@ -0,0 +1,122 @@
+
+.. highlight:: sh
+
+Documenting Your Project
+========================
+
+At this point we assume you already have created a new project, and established
+the Git repo for it etc.
+
+Now we'll walk through the steps for creating documentation for your project.
+We won't get too far in the weeds here but will seek to establish a foundation
+to which you can easily add later.
+
+The reason we cover docs so early in the game, is because as this tutorial
+project itself is being built, the docs in practice will come before most of
+the app code.  So we are just documenting steps as we encounter them, while
+building the tutorial.
+
+Install Sphinx
+--------------
+
+As is typical for Python projects, the docs we maintain within our project will
+use `Sphinx`_, which in turn uses `reStructuredText`_ for the primary syntax.
+Sphinx offers a lot of convenience, and is configurable, can be extended etc.
+
+.. _Sphinx: https://www.sphinx-doc.org/
+.. _reStructuredText: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html
+
+You may not yet have Sphinx installed to your virtualenv, but we can fix that
+now.  Run this command just to be sure::
+
+   pip install rattail[docs]
+
+Sphinx Quickstart
+-----------------
+
+Sphinx comes with a "quickstart" command, which you can use to walk through the
+process of creating a new documentation folder.
+
+First change directory to your project's source repo folder, then run the
+quickstart command like so.  Note, this will create a 'docs' folder::
+
+   cd ~/src/rattail-tutorial
+   sphinx-quickstart --project rattail-tutorial docs
+    
+You will be prompted for a few things, mostly you can use the default option or
+provide some basic answer to each, and it will work out okay.
+
+Before you go any further you may want to consider committing the generated
+docs code as-is, to help keep track of changes *you* make from there::
+
+   git add docs
+   git commit -m "Initial docs as generated by sphinx-quickstart"
+
+Building the Docs
+-----------------
+
+With the above steps complete, you should have a basic docs folder with some
+minimal default content, in reStructuredText format.
+
+These docs must be "built" which generates HTML (or other formats) from the
+reST source.  This is how you'll (re-)build docs from now on::
+
+   cd ~/src/rattail-tutorial/docs
+   make html
+
+This will generate HTML within the ``_build`` folder underneath the docs
+folder.  You can then view these docs e.g. with::
+
+   firefox _build/html/index.html
+
+Note that each time docs are built, it tries to avoid re-building things which
+haven't changed since last build.  It sometimes may be helpful to "clean" the
+docs build, i.e. wipe it out so the next build is forced to rebuild
+everything::
+
+   make clean
+   make html
+
+Now if you check your git status, you'll probably see the ``_build`` folder is
+considered "untracked" by git.  However we don't want git to concern itself
+with this folder at all, so we should ignore that, e.g. by doing::
+
+   cd ~/src/rattail-tutorial
+   echo 'docs/_build/' >> .gitignore
+   git add .gitignore
+   git commit -m "Ignore docs build folder"
+
+And finally, there is another gotcha which you won't notice until you clone
+your project's source repo to another location, and try to build docs there.
+It's not a real big deal, but you may see a warning when the docs are building,
+such as:
+
+.. code-block:: none
+
+   copying static files... WARNING: html_static_path entry '.../src/rattail-tutorial/docs/_static' does not exist
+
+To prevent that, we'll add a stub file to our repo which will ensure that
+folder always exists::
+
+   cd ~/src/rattail-tutorial
+   mkdir -p docs/_static
+   touch docs/_static/.keepme
+   git add docs/_static/.keepme
+   git commit -m "Add stub file to prevent docs build warning"
+
+Writing Some Docs!
+------------------
+
+Again it may not make sense for you to do much of this, at this point in the
+game.
+
+But while building this tutorial, all docs written up to this point have *not*
+been part of the project's docs repo proper, but rather were created as simple
+ad-hoc text files.  So our next step is simply to "transfer" all docs content
+created thus far, from these ad-hoc files, into the project docs folder.
+
+This was a pretty manual process, then at the end we commit all changes::
+
+   cd ~/src/rattail-tutorial
+   git add docs
+   git commit -m "Transfer ad-hoc setup docs to tutorial project"