Skip to content

D
django-wiki
Commit 3b7420ec by Luke Plant
Options

Beginnings of docs - converted from README

parent 2eaf23ef
Showing with 214 additions and 129 deletions
README.md
......@@ -101,138 +101,15 @@ Django needs a mature wiki system appealing to all kinds of needs, both big and
* **Be simple.** The source code should *almost* explain itself.
* **Be structured.** Markdown is a simple syntax for readability. Features should be implemented either through easy coding patterns in the content field, but rather stored in a structured way (in the database) and managed through a friendly interface. This gives control back to the website developer, and makes knowledge more usable. Just ask: Why has Wikipedia never changed? Answer: Because it's knowledge is stored in a complicated way, thus it becomes very static.
Installation
------------
### Pre-requisites
For image processing, django-wiki uses the [Pillow library](https://github.com/python-imaging/Pillow) (af fork of PIL). The preferred method should be to get a system-wide, pre-compiled version of Pillow, for instance by getting the binaries from your Linux distribution repos.
**Debian-based Linux Distros**
You may find this a bit annoying: On Ubuntu 12.04 and Debian, PIL is satisfied by installing `python-imaging`, however Pillow is not! On later versions of Ubuntu (tested on 13.10), Pillow is satisfied, but PIL is not. But since PIL no longer compiles on later releases of Ubuntu, we have opted to use Pillow. The alternative would be that django-wiki's requirements would be installed and silently fail (i.e. PIL from pip compiles on Ubuntu 13+ but finds no system libraries for image processing).
If you are on Ubuntu 13+, you may install a system-wide Pillow-adequate library like so:
sudo apt-get install python-imaging
After, you can verify that Pillow is satisfied by running `pip show Pillow`.
$ pip show Pillow
---
Name: Pillow
Version: 2.0.0
Location: /usr/lib/python2.7/dist-packages
On Ubuntu 12.04, Debian Wheezy, Jessie etc., you should acquire a system-wide installation of Pillow, read next section...
**Pip installation**
Firstly, you need to get development libraries that PIP needs before compiling. For instance on Debian/Ubuntu 12.04:
sudo apt-get install libjpeg8 libjpeg-dev libpng libpng-dev
Later versions of Ubuntu:
sudo apt-get install libjpeg8 libjpeg-dev libpng12-0 libpng12-dev
After that, install with `sudo pip install Pillow`. You might as well install Pillow system-wide, because there are little version-specific dependencies in Django applications when it comes to Pillow, and having multiple installations of the very same package is a bad practice in this case.
**Mac OS X 10.5+**
[Ethan Tira-Thompson](http://ethan.tira-thompson.com/Mac_OS_X_Ports.html) has created ports for OS X and made them available as a .dmg installer. Download and install the universal combo package [here](http://ethan.tira-thompson.com/Mac_OS_X_Ports_files/libjpeg-libpng%20%28universal%29.dmg).
Once you have the packages installed, you can proceed to the pip installation. PIL will automatically pick up these libraries and compile them for django use.
### Install
To install the latest stable release:
`pip install wiki`
Install directly from Github (in case you have no worries about deploying our master branch directly):
`pip install git+git://github.com/benjaoming/django-wiki.git`
### Configure `settings.INSTALLED_APPS`
The following applications should be listed - NB! it's important to maintain the order due to database relational constraints:
'django.contrib.humanize',
'south',
'django_notify',
'mptt',
'sekizai',
'sorl.thumbnail',
'wiki',
'wiki.plugins.attachments',
'wiki.plugins.notifications',
'wiki.plugins.images',
'wiki.plugins.macros',
### Database
To sync and create tables, do:
python manage.py syncdb
python manage.py migrate
### Configure TEMPLATE_CONTEXT_PROCESSORS
Add `'sekizai.context_processors.sekizai'` and `'django.core.context_processors.debug'` to `settings.TEMPLATE_CONTEXT_PROCESSORS`. Please refer to the [Django docs](https://docs.djangoproject.com/en/dev/ref/settings/#template-context-processors) to see the current default setting for this variable.
In Django 1.5, it should look like this:
TEMPLATE_CONTEXT_PROCESSORS = (
"django.contrib.auth.context_processors.auth",
"django.core.context_processors.debug",
"django.core.context_processors.i18n",
"django.core.context_processors.media",
"django.core.context_processors.request",
"django.core.context_processors.static",
"django.core.context_processors.tz",
"django.contrib.messages.context_processors.messages",
"sekizai.context_processors.sekizai",
)
### Include urlpatterns
To integrate the wiki to your existing application, you shoud add the following lines at the end of your project's `urls.py`.
from wiki.urls import get_pattern as get_wiki_pattern
from django_notify.urls import get_pattern as get_notify_pattern
urlpatterns += patterns('',
(r'^notify/', get_notify_pattern()),
(r'', get_wiki_pattern())
)
Please use these function calls rather than writing your own include() call - the url namespaces aren't supposed to be customized.
The above line puts the wiki in */* so it's important to put it at the end of your urlconf. You can also put it in */wiki* by putting `'^wiki/'` as the pattern.
### Settings
For now, look in [wiki/conf/settings.py](https://github.com/benjaoming/django-wiki/blob/master/wiki/conf/settings.py) to see a list of available settings.
### Other tips
1. **Account handling:** There are simple views that handle login, logout and signup. They are on by default. Make sure to set settings.LOGIN_URL to point to your login page as many wiki views may redirect to a login page.
2. **Syntax highlighting:** Python-Markdown has a pre-shipped codehilite extension which works perfectly, so add something like `WIKI_MARKDOWN_KWARGS = {'extensions': ['footnotes', 'attr_list', 'headerid', 'extra', 'codehilite', ]}` to your settings. Currently, django-wiki shippes with a stylesheet that already has the syntax highlighting CSS rules built-in. Oh, and you need to ensure `pip install pygments` because Pygments is what the codehilite extension is using!
Plugins
------------
Add/remove the following to your `settings.INSTALLED_APPS` to enable/disable the core plugins:
* `'wiki.plugins.attachments'`
* `'wiki.plugins.images'`
* `'wiki.plugins.notifications'`
Docs
----
The notifications plugin is mandatory for an out-of-the-box installation. You can safely remove it from INSTALLED_APPS if you also override the **wiki/base.html** template.
See the docs/ folder, or read them at:
Any docs?
---------
http://django-wiki.readthedocs.org/en/latest/
**No**, but there is a `docs/` skeleton and a RTD project has been registered. If you wish to write something, you can start with contents from this page, and please ask in the google group or raise an issue if you're in doubt about whether something might change.
If you wish to add something, please ask in the google group or raise an issue
if you're in doubt about whether something might change.
Background
----------
......
docs/index.rst
......@@ -11,6 +11,10 @@ Contents:
.. toctree::
:maxdepth: 2
installation
plugins
settings
tips
Indices and tables
......
docs/installation.rst 0 → 100644
Installation
============
Pre-requisites
--------------
For image processing, django-wiki uses the `Pillow
library <https://github.com/python-imaging/Pillow>`_ (a fork of PIL).
The preferred method should be to get a system-wide, pre-compiled
version of Pillow, for instance by getting the binaries from your Linux
distribution repos.
Debian-based Linux Distros
~~~~~~~~~~~~~~~~~~~~~~~~~~
You may find this a bit annoying: On Ubuntu 12.04 and Debian, PIL is
satisfied by installing ``python-imaging``, however Pillow is not! On
later versions of Ubuntu (tested on 13.10), Pillow is satisfied, but PIL
is not. But since PIL no longer compiles on later releases of Ubuntu, we
have opted to use Pillow. The alternative would be that django-wiki's
requirements would be installed and silently fail (i.e. PIL from pip
compiles on Ubuntu 13+ but finds no system libraries for image
processing).
If you are on Ubuntu 13+, you may install a system-wide Pillow-adequate
library like so:
::
sudo apt-get install python-imaging
After, you can verify that Pillow is satisfied by running
``pip show Pillow``.
::
$ pip show Pillow
---
Name: Pillow
Version: 2.0.0
Location: /usr/lib/python2.7/dist-packages
On Ubuntu 12.04, Debian Wheezy, Jessie etc., you should acquire a
system-wide installation of Pillow, read next section...
Pip installation
~~~~~~~~~~~~~~~~
Firstly, you need to get development libraries that PIP needs before
compiling. For instance on Debian/Ubuntu 12.04:
::
sudo apt-get install libjpeg8 libjpeg-dev libpng libpng-dev
Later versions of Ubuntu:
::
sudo apt-get install libjpeg8 libjpeg-dev libpng12-0 libpng12-dev
After that, install with ``sudo pip install Pillow``. You might as well
install Pillow system-wide, because there are little version-specific
dependencies in Django applications when it comes to Pillow, and having
multiple installations of the very same package is a bad practice in
this case.
Mac OS X 10.5+
~~~~~~~~~~~~~~
`Ethan
Tira-Thompson <http://ethan.tira-thompson.com/Mac_OS_X_Ports.html>`_ has
created ports for OS X and made them available as a .dmg installer.
Download and install the universal combo package
`here <http://ethan.tira-thompson.com/Mac_OS_X_Ports_files/libjpeg-libpng%20%28universal%29.dmg>`_.
Once you have the packages installed, you can proceed to the pip
installation. PIL will automatically pick up these libraries and compile
them for django use.
Install
-------
To install the latest stable release:
``pip install wiki``
Install directly from Github (in case you have no worries about
deploying our master branch directly):
``pip install git+git://github.com/benjaoming/django-wiki.git``
Configure ``settings.INSTALLED_APPS``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following applications should be listed - NB! it's important to
maintain the order due to database relational constraints:
::
'django.contrib.humanize',
'south',
'django_notify',
'mptt',
'sekizai',
'sorl.thumbnail',
'wiki',
'wiki.plugins.attachments',
'wiki.plugins.notifications',
'wiki.plugins.images',
'wiki.plugins.macros',
Database
~~~~~~~~
To sync and create tables, do:
::
python manage.py syncdb
python manage.py migrate
Configure ``TEMPLATE_CONTEXT_PROCESSORS``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Add ``'sekizai.context_processors.sekizai'`` and
``'django.core.context_processors.debug'`` to
``settings.TEMPLATE_CONTEXT_PROCESSORS``. Please refer to the `Django
docs <https://docs.djangoproject.com/en/dev/ref/settings/#template-context-processors>`_
to see the current default setting for this variable.
In Django 1.5, it should look like this:
::
TEMPLATE_CONTEXT_PROCESSORS = (
"django.contrib.auth.context_processors.auth",
"django.core.context_processors.debug",
"django.core.context_processors.i18n",
"django.core.context_processors.media",
"django.core.context_processors.request",
"django.core.context_processors.static",
"django.core.context_processors.tz",
"django.contrib.messages.context_processors.messages",
"sekizai.context_processors.sekizai",
)
Include urlpatterns
~~~~~~~~~~~~~~~~~~~
To integrate the wiki to your existing application, you shoud add the
following lines at the end of your project's ``urls.py``.
::
from wiki.urls import get_pattern as get_wiki_pattern
from django_notify.urls import get_pattern as get_notify_pattern
urlpatterns += patterns('',
(r'^notify/', get_notify_pattern()),
(r'', get_wiki_pattern())
)
Please use these function calls rather than writing your own include()
call - the url namespaces aren't supposed to be customized.
The above line puts the wiki in */* so it's important to put it at the
end of your urlconf. You can also put it in */wiki* by putting
``'^wiki/'`` as the pattern.
docs/plugins.rst 0 → 100644
Plugins
=======
Add/remove the following to your ``settings.INSTALLED_APPS`` to
enable/disable the core plugins:
- ``'wiki.plugins.attachments'``
- ``'wiki.plugins.images'``
- ``'wiki.plugins.notifications'``
The notifications plugin is mandatory for an out-of-the-box installation. You
can safely remove it from ``INSTALLED_APPS`` if you also override the
**wiki/base.html** template.
docs/settings.rst 0 → 100644
Settings
========
For now, look in
`wiki/conf/settings.py <https://github.com/benjaoming/django-wiki/blob/master/wiki/conf/settings.py>`_
to see a list of available settings.
docs/tips.rst 0 → 100644
Other tips
==========
1. **Account handling:** There are simple views that handle login,
logout and signup. They are on by default. Make sure to set
``settings.LOGIN_URL`` to point to your login page as many wiki views
may redirect to a login page.
2. **Syntax highlighting:** Python-Markdown has a pre-shipped codehilite
extension which works perfectly, so add something like::
WIKI_MARKDOWN_KWARGS = {'extensions': ['footnotes', 'attr_list', 'headerid', 'extra', 'codehilite', ]}
to your settings. Currently, django-wiki shippes with a stylesheet
that already has the syntax highlighting CSS rules built-in. Oh, and
you need to ensure ``pip install pygments`` because Pygments is what
the codehilite extension is using!
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment