.. _topics-install:

==========================================
How to install Softwarefabrica Django Wiki
==========================================

.. admonition:: About this document

   This document describes how to install Softwarefabrica Django Wiki and use it
   in your Django applications.

.. contents::
   :depth: 3

.. _pre-requisites:

Pre-requisites
==============

This library depends on `softwarefabrica.django.utils`_,
`softwarefabrica.django.forms`_, `softwarefabrica.django.crud`_ and `sflib`_
from the same author.
If you use EasyInstall_, as outlined below, dependencies will be satisfied
automatically (the ``easy_install`` command will take care of everything).

.. _EasyInstall: http://peak.telecommunity.com/DevCenter/EasyInstall
.. _`softwarefabrica.django.utils`: http://pypi.python.org/pypi/softwarefabrica.django.utils
.. _`softwarefabrica.django.forms`: http://pypi.python.org/pypi/softwarefabrica.django.forms
.. _`softwarefabrica.django.crud`: http://pypi.python.org/pypi/softwarefabrica.django.crud
.. _`sflib`: http://pypi.python.org/pypi/sflib

.. _installing-official-release:

Installing an official release
==============================

Official releases are made available from PyPI_

http://pypi.python.org/pypi/softwarefabrica.django.wiki

Source distribution
-------------------

If you have EasyInstall_ available, you can download and install the most
up-to-date version in one step. For example, on a unix-like system:

::

  $ su
  # easy_install softwarefabrica.django.wiki

If you are using Ubuntu, to install system-wide:

::

  $ sudo easy_install softwarefabrica.django.wiki

Otherwise, if EasyInstall_ is not available, you can just download the `source
distribution`_ (eg. from PyPI_), extract it and run the usual ``setup.py`` commands:

::

  $ su
  # python setup.py install

These commands will install the software in your Python installation's
``site-packages`` directory.

.. _EasyInstall: http://peak.telecommunity.com/DevCenter/EasyInstall
.. _PyPI: http://pypi.python.org/pypi
.. _`source distribution`: http://pypi.python.org/pypi/softwarefabrica.django.wiki


Windows installer
-----------------

A Windows installer will be made available in a next release.

.. _installing-development-version:

Installing the development version
==================================

Alternatively, if you'd like to update the software occasionally to pick
up the latest bug fixes and enhancements before they make it into an
offical release, branch from the `Bazaar`_ repository hosted on `LaunchPad`_
instead.
Just follow the procedure outlined below:

1. Make sure that you have `Bazaar`_ installed, and that you can run its
   commands from a shell. (Enter ``bzr help`` at a shell prompt to test
   this.)

2. Create a local branch and working tree from the official one::

    bzr branch lp:sf-django-wiki sf-wiki

3. Then from the ``sf-wiki`` directory you can run the ``setup.py develop``
   command to install the library in your Python `site-packages` directory
   using a link, which allows to continue developing inside the working tree
   without the need to re-install after every change. See the
   `setuptools development mode`_ documention for more information::

    $ sudo
    # python setup.py develop

4. You can verify that the application is available on your `PYTHONPATH`_ by
   opening a Python interpreter and entering the following commands::

    >>> from softwarefabrica.django.wiki import version
    >>> version.VERSION
    (1, 0, 'dev')
    >>> version.get_version()
    u'1.0-dev-BZR-rXX-panta@elasticworld.org-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'

When you want to update your copy of the library source code, run the command
``bzr pull`` from within the ``sf-wiki`` directory::

    bzr pull
    sudo python setup.py develop

(you need to re-run the ``setup.py develop`` command after every working tree
update, to update version numbers in script wrappers).

.. caution::

   The development version may contain bugs which are not present in the
   release version and introduce backwards-incompatible changes.

   If you're tracking trunk, keep an eye on the `changes`_ before you update
   your copy of the source code.

.. _`development home page`: https://launchpad.net/sf-django-wiki
.. _`bugs`: https://bugs.launchpad.net/sf-django-wiki
.. _`LaunchPad`: http://launchpad.net
.. _`Bazaar`: http://bazaar-vcs.org/
.. _`changes`: http://bazaar.launchpad.net/~softwarefabrica/sf-django-wiki/trunk/changes
.. _`PYTHONPATH`: http://docs.python.org/tut/node8.html#SECTION008110000000000000000
.. _`junction`: http://www.microsoft.com/technet/sysinternals/FileAndDisk/Junction.mspx
.. _`setuptools development mode`: http://peak.telecommunity.com/DevCenter/setuptools#development-mode

Using the wiki in your projects
===============================

Once you've installed the library and want to use it in your Django
projects, simply put ``'softwarefabrica.django.wiki'`` in your
``INSTALLED_APPS`` setting, after its dependencies
(``'softwarefabrica.django.utils'``, ``'softwarefabrica.django.forms'`` and
``'softwarefabrica.django.crud'``) and ``'django.contrib.markup'``. Also add an
entry in your root URLconf for the wiki URLs and views.

Then remember to issue a ``manage.py syncdb`` command, to create the necessary
database tables.

Let's recap:

1. Put ``'softwarefabrica.django.utils'`` and its dependencies in your
   ``INSTALLED_APPS`` setting::

     INSTALLED_APPS = (
         ..
	 'django.contrib.markup',
         'softwarefabrica.django.utils',
         'softwarefabrica.django.forms',
         'softwarefabrica.django.crud',
         'softwarefabrica.django.wiki',
     )

2. Add a proper line in your root URLconf to point to the wiki URLs, such
   as::

     (r'wiki/', include('softwarefabrica.django.wiki.urls')),

3. Run the ``manage.py syncdb`` command::

     python manage.py syncdb

That's it!

.. _utilities:

Utilities
=========

See the `utilities guide document`_.

.. _`utilities guide document`: utilities.html

.. _demo-project:

Demo project
============

There is a demo project included, which should give an example on how to use the
wiki application. It's available in the ``demoproj`` subdirectory.

To run the development server on the demo project, enter the directory, set
``DJANGO_SETTINGS_MODULE``, then run ``manage.py syncdb`` and ``manage.py
runserver``:

::

  $ cd demoproj
  $ export DJANGO_SETTINGS_MODULE=demoproj.settings
  $ python manage.py syncdb
  $ python manage.py runserver

or just use the included ``setup`` shell script to set environment variables (it
must be `sourced`):

::

  $ cd demoproj
  $ . setup
  $ python manage.py syncdb
  $ python manage.py runserver

Then point your browser at `localhost:8000`.

The administration is at at `localhost:8000/admin`. The default administrator
user is ``wiki``, with password ``wiki``. Don't use it on production :-)

.. _`models documentation`: models.html
