rattail/rattail-tutorial
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Transfer ad-hoc setup docs to tutorial project

Browse source
This commit is contained in:
Lance Edgar 2019-08-16 18:58:29 -05:00
parent 7d726b9f79
commit 4d35e43c15
6 changed files with 654 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

8
Vagrantfile vendored Normal file
View file

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

4
docs/conf.py
View file

@ -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 -------------------------------------------------

194
docs/create-project.rst Normal file
View file

@ -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.)

58
docs/index.rst
View file

@ -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

275
docs/setup-dev.rst Normal file
View file

@ -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")

122
docs/start-docs.rst Normal file
View file

@ -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"