Transfer ad-hoc setup docs to tutorial project
This commit is contained in:
Lance Edgar
parent
7d726b9f79
commit
4d35e43c15
8
Vagrantfile
vendored
Normal file
8
Vagrantfile
vendored
Normal file
|
|
@ -0,0 +1,8 @@
|
|||
# -*- mode: ruby; -*-
|
||||
|
||||
Vagrant.configure("2") do |config|
|
||||
|
||||
# target machine runs Debian 10 "buster"
|
||||
config.vm.box = "debian/buster64"
|
||||
|
||||
end
|
||||
|
|
@ -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
194
docs/create-project.rst
Normal 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.)
|
||||
|
|
@ -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
275
docs/setup-dev.rst
Normal 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
122
docs/start-docs.rst
Normal 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"
|
||||
Loading…
Reference in a new issue