Add getting started doc for dev environment

also change docs theme

docs/conf.py

@@ -1,4 +1,4 @@
-# -*- coding: utf-8 -*-
+# -*- coding: utf-8; -*-
 #
 # Tailbone documentation build configuration file, created by
 # sphinx-quickstart on Sat Feb 15 23:15:27 2014.
@@ -15,6 +15,8 @@
 import sys
 import os
 
+import sphinx_rtd_theme
+
 exec(open(os.path.join(os.pardir, 'tailbone', '_version.py')).read())
 
 
@@ -58,14 +60,15 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'Tailbone'
-copyright = u'2015, Lance Edgar'
+copyright = u'2010 - 2018, Lance Edgar'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '0.3'
+# version = '0.3'
+version = '.'.join(__version__.split('.')[:2])
 # The full version, including alpha/beta/rc tags.
 release = __version__
 
@@ -112,7 +115,8 @@ pygments_style = 'sphinx'
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'classic'
+# html_theme = 'classic'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -121,6 +125,7 @@ html_theme = 'classic'
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -132,6 +137,7 @@ html_theme = 'classic'
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 #html_logo = None
+html_logo = 'images/rattail_avatar.png'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32

docs/devenv.rst

@@ -0,0 +1,78 @@
+
+Development Environment
+=======================
+
+.. contents:: :local:
+
+Base System
+-----------
+
+Development for Tailbone in particular is assumed to occur on a Linux machine.
+This is because it's assumed that the web app would run on Linux.  It should be
+possible (presumably) to do either on Windows or Mac but that is not officially
+supported.
+
+Furthermore it is assumed the Linux flavor in use is either Debian or Ubuntu,
+or a similar alternative.  Presumably any Linux would work although some
+details may differ from what's shown here.
+
+Prerequisites
+-------------
+
+Python
+^^^^^^
+
+The only supported Python is 2.7.  Of course that should already be present on
+Linux.
+
+It usually is required at some point to compile C code for certain Python
+extension modules.  In practice this means you probably want the Python header
+files as well:
+
+.. code-block:: sh
+
+   sudo apt-get install python-dev
+
+pip
+^^^
+
+The only supported Python package manager is ``pip``.  This can be installed a
+few ways, one of which is:
+
+.. code-block:: sh
+
+   sudo apt-get install python-pip
+
+virtualenvwrapper
+^^^^^^^^^^^^^^^^^
+
+While not technically required, it is recommended to use ``virtualenvwrapper``
+as well.  There is more than one way to set this up, e.g.:
+
+.. code-block:: sh
+
+   sudo apt-get install python-virtualenvwrapper
+
+The main variable as concerns these docs, is where your virtual environment(s)
+will live.  If you install virtualenvwrapper via the above command, then most
+likely your ``$WORKON_HOME`` environment variable will be set to
+``~/.virtualenvs`` - however these docs will assume ``/srv/envs`` instead.
+Please adjust any commands as needed.
+
+PostgreSQL
+^^^^^^^^^^
+
+The other primary requirement is PostgreSQL.  Technically that may be installed
+on a separate machine, which allows connection from the development machine.
+But of course it will usually just be installed on the dev machine:
+
+.. code-block:: sh
+
+   sudo apt-get install postgresql
+
+Regardless of where your PG server lives, you will probably need some extras in
+order to compile extensions for the ``psycopg2`` package:
+
+.. code-block:: sh
+
+   sudo apt-get install libpq-dev

docs/index.rst

@@ -4,6 +4,10 @@ Tailbone
 
 Welcome to Tailbone, part of the Rattail project.
 
+..
+   While the core Rattail package provides the data schema / ORM / application
+   layer, the Tailbone package provides the web application layer.
+
 The documentation you are currently reading is for the Tailbone web application
 package.  Some additional information is available on the `website`_.  Clearly
 not everything is documented yet.  Below you can see what has received some
@@ -11,6 +15,13 @@ attention thus far.
 
 .. _website: https://rattailproject.org/
 
+Getting Started:
+
+.. toctree::
+   :maxdepth: 1
+
+   devenv
+
 Narrative Documentation:
 
 .. toctree::

setup.py

@@ -2,7 +2,7 @@
 ################################################################################
 #
 #  Rattail -- Retail Software Framework
-#  Copyright © 2010-2017 Lance Edgar
+#  Copyright © 2010-2018 Lance Edgar
 #
 #  This file is part of Rattail.
 #
@@ -112,6 +112,7 @@ extras = {
         # package                       # low                   high
 
         'Sphinx',                       # 1.2
+        'sphinx-rtd-theme',             # 0.2.4
     ],
 
     'tests': [
@@ -123,7 +124,7 @@ extras = {
         'mock',                         # 1.0.1
         'nose',                         # 1.3.0
     ],
-    }
+}
 
 
 setup(