From c44cbe9a955fe14cd161f3527d7ec0a71395bb9f Mon Sep 17 00:00:00 2001 From: Evgeny Fadeev Date: Sun, 12 Dec 2010 17:02:43 -0500 Subject: updated documentation --- askbot/doc/source/compile-time-configuration.rst | 38 --------------- askbot/doc/source/conf.py | 8 ++-- askbot/doc/source/create-database.rst | 36 ++++++++++++++ askbot/doc/source/index.rst | 34 ++++++------- askbot/doc/source/initial-configuration.rst | 38 +++++++++++++++ askbot/doc/source/install-easy-install.rst | 45 ----------------- askbot/doc/source/install.rst | 61 ++++++++++++++++++++++++ askbot/doc/source/pre-requisites.rst | 42 ---------------- 8 files changed, 154 insertions(+), 148 deletions(-) delete mode 100644 askbot/doc/source/compile-time-configuration.rst create mode 100644 askbot/doc/source/create-database.rst create mode 100644 askbot/doc/source/initial-configuration.rst delete mode 100644 askbot/doc/source/install-easy-install.rst create mode 100644 askbot/doc/source/install.rst delete mode 100644 askbot/doc/source/pre-requisites.rst diff --git a/askbot/doc/source/compile-time-configuration.rst b/askbot/doc/source/compile-time-configuration.rst deleted file mode 100644 index 3e15dde4..00000000 --- a/askbot/doc/source/compile-time-configuration.rst +++ /dev/null @@ -1,38 +0,0 @@ -.. _compile-time-configuration: - -=============================== -Initial Configuration of Askbot -=============================== - -While most configuration settings for askbot can be done at any time :ref:`through the web-interface `, some manipulations on the server are still necessary. - -When you are installing askbot the first time you will need to initialize the site setup files by typing:: - - startforum - -and answering the questions. - -The startforum script will attempt to create necessary directories and copy files. - -If you are creating a brand new Django project, then you will need to edit file `settings.py`_ - -In the case you are adding askbot to an existing Django project, you will need to -merge askbot files settings.py_ and urls.py_ into your project files manually. - -.. note:: - - Files settings.py_ and urls.py_ may also need to be touched up - when you upgrate the software, because new versions may bring - new dependencies and add new site urls. - - -Within settings.py, at the very minimum you will need to provide correct values to:: - - DATABASE_NAME = '' - DATABASE_USER = '' - DATABASE_PASSWORD = '' - -within single quotes - login credentials to your mysql database. - -.. _urls.py: http://github.com/ASKBOT/askbot-devel/blob/master/askbot/setup_templates/urls.py -.. _settings.py: http://github.com/ASKBOT/askbot-devel/blob/master/askbot/setup_templates/settings.py 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/create-database.rst b/askbot/doc/source/create-database.rst new file mode 100644 index 00000000..f803cf89 --- /dev/null +++ b/askbot/doc/source/create-database.rst @@ -0,0 +1,36 @@ +.. _create-database: + +========================== +Create database for Askbot +========================== + +Askbot has been successfully tested with `MySQL` and `PostgresQL` databases. + +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 +can be created manually as shown below (using a high privilege MySQL account): + +Log in to mysql:: + + mysql -u username -p + +Then type these two commands (note that fake `dbname`, `dbuser`, and `dbpassword` are used in this example):: + + create database askbot DEFAULT CHARACTER SET UTF8 COLLATE utf8_general_ci; + grant all privileges on dbname.* to dbuser@localhost identified by 'dbpassword'; + +Again, please remember to create real usernname, database name and password and write them down. These +credentials will go into the file `settings.py`_ - the main configuration file of the Django application. + +.. note:: + + Notation `dbuser@hostname` is important for security - normally you want to restrict access to + the database to certain hosts only. `localhost` entry ensures that database cannot be accessed + from remote hosts at all. + +.. _Python: http://www.python.org/download/ +.. _MySQL: http://www.mysql.com/downloads/mysql/#downloads +.. _settings.py: http://github.com/ASKBOT/askbot-devel/blob/master/askbot/setup_templates/settings.py 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 `_ 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 ` + Install the software + Create the database + Create and configure the site files + Initialize the database tables + Deploy on a webserver -Install - :ref:`latest stable version ` or `development version`_. - -Configure - (1) :ref:`edit settings files ` -(2) :ref:`initialize the application database ` (3) :ref:`configure the running site ` - -Upgrade: :ref:`to next stable version ` or to the :ref:`current development version ` - -:ref:`Maintain ` - -:ref:`Debugging techniques ` +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/initial-configuration.rst b/askbot/doc/source/initial-configuration.rst new file mode 100644 index 00000000..3e15dde4 --- /dev/null +++ b/askbot/doc/source/initial-configuration.rst @@ -0,0 +1,38 @@ +.. _compile-time-configuration: + +=============================== +Initial Configuration of Askbot +=============================== + +While most configuration settings for askbot can be done at any time :ref:`through the web-interface `, some manipulations on the server are still necessary. + +When you are installing askbot the first time you will need to initialize the site setup files by typing:: + + startforum + +and answering the questions. + +The startforum script will attempt to create necessary directories and copy files. + +If you are creating a brand new Django project, then you will need to edit file `settings.py`_ + +In the case you are adding askbot to an existing Django project, you will need to +merge askbot files settings.py_ and urls.py_ into your project files manually. + +.. note:: + + Files settings.py_ and urls.py_ may also need to be touched up + when you upgrate the software, because new versions may bring + new dependencies and add new site urls. + + +Within settings.py, at the very minimum you will need to provide correct values to:: + + DATABASE_NAME = '' + DATABASE_USER = '' + DATABASE_PASSWORD = '' + +within single quotes - login credentials to your mysql database. + +.. _urls.py: http://github.com/ASKBOT/askbot-devel/blob/master/askbot/setup_templates/urls.py +.. _settings.py: http://github.com/ASKBOT/askbot-devel/blob/master/askbot/setup_templates/settings.py 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) `_ - -.. 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 `_, 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 `_ 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 ` will help you find those components. - -When you have all packages installed, -please proceed to the :ref:`initial 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) `_ + +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 `_, 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 + +where `` 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 `_ 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 ` will help you find those components. + +When you have all packages installed, +please proceed to the :ref:`initial 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/pre-requisites.rst b/askbot/doc/source/pre-requisites.rst deleted file mode 100644 index 83591b19..00000000 --- a/askbot/doc/source/pre-requisites.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. _pre-requisites: - -========================= -Prerequisites for Askbot -========================= -Askbot installation currently requires: - -* 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 - -For the production :ref:`deployment` you will also need a webserver capable to run -python web applications. - -Creating a database instance ------------------------------ -This section assumes that MySQL is installed and is up and running. - -Database can be prepared via your hosting control panel, if available, or -can be created manually as shown below (using a high privilege MySQL account): - -Log in to mysql:: - - mysql -u username -p - -Then type these two commands (note that fake `dbname`, `dbuser`, and `dbpassword` are used in this example):: - - create database askbot DEFAULT CHARACTER SET UTF8 COLLATE utf8_general_ci; - grant all privileges on dbname.* to dbuser@localhost identified by 'dbpassword'; - -Again, please remember to create real usernname, database name and password and write them down. These -credentials will go into the file `settings.py`_ - the main configuration file of the Django application. - -.. note:: - - Notation `dbuser@hostname` is important for security - normally you want to restrict access to - the database to certain hosts only. `localhost` entry ensures that database cannot be accessed - from remote hosts at all. - -.. _Python: http://www.python.org/download/ -.. _MySQL: http://www.mysql.com/downloads/mysql/#downloads -.. _settings.py: http://github.com/ASKBOT/askbot-devel/blob/master/askbot/setup_templates/settings.py -- cgit v1.2.3-1-g7c22