# How to install Softwarefabrica Django Wiki

About this document

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

Contents

- Pre-requisites
- Installing an official release
  - Source distribution
  - Windows installer
- Installing the development version
- Using the wiki in your projects
- Utilities
- Demo project

# 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).

# 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.

## Windows installer

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

# 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.

# 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

See the utilities guide document.

# 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 :-)