updated documentation

6 files changed, 87 insertions, 81 deletions

diff --git a/askbot/doc/source/conf.py b/askbot/doc/source/conf.py
index 0a02d298..1039dff0 100644
--- a/askbot/doc/source/conf.py
+++ b/askbot/doc/source/conf.py
@@ -110,10 +110,10 @@ modindex_common_prefix = ['askbot.']
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
-html_theme_options = {
-    'rightsidebar':'true',
-}
+html_theme = 'traditional'
+#html_theme_options = {
+#    'rightsidebar':'false',
+#}
 
 # 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
diff --git a/askbot/doc/source/pre-requisites.rst b/askbot/doc/source/create-database.rst
index 83591b19..f803cf89 100644
--- a/askbot/doc/source/pre-requisites.rst
+++ b/askbot/doc/source/create-database.rst
@@ -1,19 +1,13 @@
-.. _pre-requisites:
+.. _create-database:
 
-=========================
-Prerequisites for Askbot
-=========================
-Askbot installation currently requires:
+==========================
+Create database for Askbot
+==========================
 
-* Python_ version 2.4 - 2.6 (Version 3 is not yet supported)
-* MySQL_ version 5
-* access to an instance of MySQL database with full privileges
+Askbot has been successfully tested with `MySQL` and `PostgresQL` databases.
 
-For the production :ref:`deployment` you will also need a webserver capable to run
-python web applications.
-
-Creating a database instance
------------------------------
+MySQL
+-----
 This section assumes that MySQL is installed and is up and running.
 
 Database can be prepared via your hosting control panel, if available, or
diff --git a/askbot/doc/source/index.rst b/askbot/doc/source/index.rst
index a222e314..c7617cfa 100644
--- a/askbot/doc/source/index.rst
+++ b/askbot/doc/source/index.rst
@@ -4,29 +4,25 @@
 Askbot Project Documentation
 =============================
 
-Askbot is an open source Question and Answer (Q&A) forum project inspired by StackOverflow_ 
-and YahooAnswers_. Askbot is written in Python_ on top of the Django_ platform.
-Code of Askbot grew out of CNPROG_ project originally written by 
-`Mike Chen <http://cn.linkedin.com/in/mikegangchen>`_ and Sailing Cai.
+Askbot is an open source Question and Answer (Q&A) forum project inspired by StackOverflow 
+and YahooAnswers.
 
-.. note::
+It is quick and easy to install and deploy askbot on your site.
+Have questions? - please ask
+at the forum_ or by email at admin@askbot.org
 
-    If you have any questions installing or tweaking askbot - please do not hesitate to ask
-    at the forum_ or by email at admin@askbot.org. This documentation is in the active development
-    - if you notice any omissions - please don't hesitate to contact us.
+.. toctree::
+   :maxdepth: 1
 
-:ref:`Pre-requisites <pre-requisites>`
+   Install the software <install>
+   Create the database <create-database>
+   Create and configure the site files<initial-configuration>
+   Initialize the database tables <initialize-database-tables>
+   Deploy on a webserver <deployment>
 
-Install - :ref:`latest stable version <install-easy-install>` or `development version`_.
-
-Configure - (1) :ref:`edit settings files <compile-time-configuration>`
-(2) :ref:`initialize the application database <initialize-database-tables>` (3) :ref:`configure the running site <run-time-configuration>`
-
-Upgrade: :ref:`to next stable version <upgrade-with-easy-install>` or to the :ref:`current development version <upgrading-with-git>`
-
-:ref:`Maintain <maintenance>`
-
-:ref:`Debugging techniques <debugging>`
+Some background information: Askbot is written in Python on top of the Django platform.
+Code of Askbot grew out of CNPROG project originally written by 
+Mike Chen and Sailing Cai.
 
 .. _Python: http://www.python.org/download/
 .. _YahooAnswers: http://answers.yahoo.com/
diff --git a/askbot/doc/source/compile-time-configuration.rst b/askbot/doc/source/initial-configuration.rst
index 3e15dde4..3e15dde4 100644
--- a/askbot/doc/source/compile-time-configuration.rst
+++ b/askbot/doc/source/initial-configuration.rst
diff --git a/askbot/doc/source/install-easy-install.rst b/askbot/doc/source/install-easy-install.rst
deleted file mode 100644
index 80513d0a..00000000
--- a/askbot/doc/source/install-easy-install.rst
+++ /dev/null
@@ -1,45 +0,0 @@
-.. _install-easy-install:
-
-===========================================================
-Installing Askbot with easy_install (python package index).
-===========================================================
-
-The latest stable version of askbot can be installed from the official `Python Package Index (PyPI) <http://pypi.python.org/pypi/askbot/>`_
-
-.. note::
-
-    To simplify future deployment, please make sure to use the same python 
-    interpreter for the installation and testing as the one assigned 
-    (or will be assigned) to the webserver.
-    The same applies to easy_install tool, and the `PYTHONPATH`
-    environment variable.
-
-If you already have `easy_install`_ (python setuptools) on your system, then type::
-
- easy_install askbot
-
-If you do not yet have it, download the `askbot archive from PyPI <http://pypi.python.org/pypi/askbot/>`_, unzip and untar it, then run::
-
- python setup.py install
-
-Both command achieve the same effect, except the second one will also install the setuptools.
-
-.. note::
-
-    To install in non-standard locations add parameter ``--prefix=/path/to/some/dir`` to both commands.
-
-Under windows, please install 
-`mysql-python windows binary package <http://www.codegood.com/archives/4>`_ manually.
-
-Most likely, by this time you will have askbot software installed. However, in some cases
-one of the dependency packages might fail to install. :ref:`This document <dependencies>` will help you find those components.
-
-When you have all packages installed, 
-please proceed to the :ref:`initial configuration <compile-time-configuration>` section. 
-
-.. _Python: http://www.python.org/download/
-.. _askbot: http://pypi.python.org/pypi/askbot
-.. _`easy_install`: http://pypi.python.org/pypi/setuptools
-.. _pypi: http://pypi.python.org/
-
-.. _django.wsgi: http://github.com/ASKBOT/askbot-devel/blob/master/askbot/setup_templates/django.wsgi
diff --git a/askbot/doc/source/install.rst b/askbot/doc/source/install.rst
new file mode 100644
index 00000000..60f6bcee
--- /dev/null
+++ b/askbot/doc/source/install.rst
@@ -0,0 +1,61 @@
+.. _install:
+
+=================
+Installing Askbot
+=================
+
+The latest stable version of askbot can be installed from the official `Python Package Index (PyPI) <http://pypi.python.org/pypi/askbot/>`_
+
+There are several methods to install Askbot. The recommended choice of the method depends on whether you are planning to modify the source code and/or templates or not.
+
+Would like to use the package as is?
+====================================
+
+If so - then the best tool for that is `pip`, the second best choice is `easy_install`::
+
+ pip install askbot
+ easy_install askbot #if you prefer easy_install
+
+Both commands automatically install Askbot and the dependency packages. `Pip` is a significant improvement upon `easy_install` and is strongly recommended.
+
+If you do not have either of those tools - download the `askbot archive from PyPI <http://pypi.python.org/pypi/askbot/>`_, unzip and untar it, then run::
+
+ python setup.py install #this is actually equivalent to running easy_install
+
+Intend to customize the forum?
+==============================
+
+In this case the best option is to clone the code from the development repository::
+
+ git clone git://github.com/ASKBOT/askbot-devel.git <project_name>
+
+where `<project_name>` should be some very distinct name.
+
+Then jump into the new directory and run::
+
+ python setup.py develop #the develop option will not install askbot into the python site packages directory
+
+How to install into custom directories
+======================================
+
+On the shared hosts and in some other cases it is better to install python packages in some place other than the system package directory. If that's your situation - use the `virtualenv` tool::
+
+ virtualenv /path/to/some/directory
+
+Virtualenv will provide a dedicated `python` interpreter and `pip` just for that isolated environment. Both will be available within directory `/path/to/some/dir/bin`. Please, use them to run operations shown above.
+
+Under windows, please install 
+`mysql-python windows binary package <http://www.codegood.com/archives/4>`_ manually.
+
+Most likely, by this time you will have askbot software installed. However, in some cases
+one of the dependency packages might fail to install. :ref:`This document <dependencies>` will help you find those components.
+
+When you have all packages installed, 
+please proceed to the :ref:`initial configuration <compile-time-configuration>` section. 
+
+.. _Python: http://www.python.org/download/
+.. _askbot: http://pypi.python.org/pypi/askbot
+.. _`easy_install`: http://pypi.python.org/pypi/setuptools
+.. _pypi: http://pypi.python.org/
+
+.. _django.wsgi: http://github.com/ASKBOT/askbot-devel/blob/master/askbot/setup_templates/django.wsgi