Add getting started doc for dev environment

also change docs theme
This commit is contained in:
Lance Edgar 2018-01-11 12:15:19 -06:00
parent c750ea2355
commit 99ed897bf4
5 changed files with 104 additions and 8 deletions

View file

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

78
docs/devenv.rst Normal file
View file

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

Binary file not shown.

After

Width:  |  Height:  |  Size: 7.6 KiB

View file

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

View file

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