diff --git a/docs/conf.py b/docs/conf.py index 4529fcc2..8cbe5273 100644 --- a/docs/conf.py +++ b/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 # " v 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 diff --git a/docs/devenv.rst b/docs/devenv.rst new file mode 100644 index 00000000..c8900f60 --- /dev/null +++ b/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 diff --git a/docs/images/rattail_avatar.png b/docs/images/rattail_avatar.png new file mode 100644 index 00000000..99640af3 Binary files /dev/null and b/docs/images/rattail_avatar.png differ diff --git a/docs/index.rst b/docs/index.rst index 3fbf704e..b5968992 100644 --- a/docs/index.rst +++ b/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:: diff --git a/setup.py b/setup.py index 96e9458d..84fbcf18 100644 --- a/setup.py +++ b/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,7 +112,8 @@ extras = { # package # low high 'Sphinx', # 1.2 - ], + 'sphinx-rtd-theme', # 0.2.4 + ], 'tests': [ # @@ -122,8 +123,8 @@ extras = { 'fixture', # 1.5 'mock', # 1.0.1 'nose', # 1.3.0 - ], - } + ], +} setup(