From 99ed897bf483111a65741997b181ee6be7e08cca Mon Sep 17 00:00:00 2001 From: Lance Edgar Date: Thu, 11 Jan 2018 12:15:19 -0600 Subject: [PATCH] Add getting started doc for dev environment also change docs theme --- docs/conf.py | 14 ++++-- docs/devenv.rst | 78 +++++++++++++++++++++++++++++++++ docs/images/rattail_avatar.png | Bin 0 -> 7770 bytes docs/index.rst | 11 +++++ setup.py | 9 ++-- 5 files changed, 104 insertions(+), 8 deletions(-) create mode 100644 docs/devenv.rst create mode 100644 docs/images/rattail_avatar.png 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 0000000000000000000000000000000000000000..99640af34c5c956f5bcb1b89b16240a6f561e60b GIT binary patch literal 7770 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 literal 0 HcmV?d00001 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(