Commit ecd2dec4 by benjaoming

Merge pull request #227 from spookylukey/easy_branding

Easy branding  + documentation
parents 2eaf23ef 051ca6eb
...@@ -101,138 +101,15 @@ Django needs a mature wiki system appealing to all kinds of needs, both big and ...@@ -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 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. * **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 Docs
------------ ----
### 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'`
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 Background
---------- ----------
......
Customization
=============
See :doc:`settings` for the settings that can be used to configure
django-wiki. Other ways to customize django-wiki for your use are listed below.
Templates
---------
django-wiki can be customized by providing your own templates.
All templates used by django-wiki inherit from ``wiki/base.html``, which in
turn simply inherits from ``wiki/base_site.html`` (adding
nothing). ``wiki/base_site.html`` provides a complete HTML page, but provides a
number of blocks that you might want to override. The most useful are:
* ``wiki_header_branding``
* ``wiki_header_navlinks``
These can be overridden to provide your own branding and links in the top bar of
the page. The ``wiki/base_site.html`` template uses Bootstrap 3, so the
following example shows how to use this in practice, assuming you want a single
link to your home page, and one to the wiki. Add the following as
``wiki/base.html`` somewhere in your ``TEMPLATE_DIRS``:
.. code-block:: html+django
{% extends "wiki/base_site.html" %}
{% block wiki_header_branding %}
<a class="navbar-brand" href="/">Your brand</a>
{% endblock %}
{% block wiki_header_navlinks %}
<ul class="nav navbar-nav">
<li class="active"><a href="{% url 'wiki:root' %}">Wiki</a></li>
</ul>
{% endblock %}
...@@ -11,6 +11,11 @@ Contents: ...@@ -11,6 +11,11 @@ Contents:
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
installation
plugins
customization
settings
tips
Indices and tables Indices and tables
......
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.
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.
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!
{% load sekizai_tags i18n wiki_tags %}{% load url from future %}<!DOCTYPE html> {% extends "wiki/base_site.html" %}
<html lang="en">
<head>
<meta charset="utf-8">
<title>{% block wiki_pagetitle %}{% endblock %} - django-\/\/ i K |</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="description" content="">
<meta name="author" content="www.django-wiki.org">
<!-- Le styles -->
<link href="{{ STATIC_URL }}wiki/bootstrap/css/wiki-bootstrap.min.css" rel="stylesheet">
{% render_block "css" %}
<!-- Le HTML5 shim, for IE6-8 support of HTML5 elements -->
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
</head>
<body>
{% block wiki_body %}
{% block wiki_navbar %}
<div class="navbar navbar-fixed-top navbar-inverse">
<div class="container">
<!-- .navbar-toggle is used as the toggle for collapsed navbar content -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-responsive-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
{% block wiki_header_branding %}
<a class="navbar-brand" href="{% url 'wiki:root' %}">django-\/\/ i K |</a>
{% endblock %}
<div class="nav-collapse collapse navbar-responsive-collapse">
<form class="navbar-form pull-right-block-on-responsive" id="wiki-search-form" method="GET" action="{% url 'wiki:search' %}">
<div class="input-group">
<input type="search" class="form-control search-query" name="q" placeholder="{% trans "Search..." %}" />
<span class="input-group-btn">
<button class="btn btn-default" type="button">
<span class="icon-search"></span>
</button>
</span>
</div><!-- /input-group -->
</form>
<div class="pull-right-block-on-responsive">
{% if user.is_authenticated %}
<ul class="nav navbar-nav">
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">
<span class="badge notification-cnt">0</span>
{{ user }}
<b class="caret"></b>
</a>
<ul class="dropdown-menu">
<li>
<a href="{% url 'wiki:logout' %}">
<i class="icon-off"></i>
{% trans "Log out" %}
</a>
</li>
{% include "wiki/plugins/notifications/menubaritem.html" %}
</ul>
</li>
</ul>
{% else %}
<ul class="nav navbar-nav">
<li>
<a href="{% login_url as wiki_login_url %}{{ wiki_login_url }}">{% trans "Log in" %}</a>
</li>
<li>
<a href="{% url 'wiki:signup' %}">{% trans "Sign up" %}</a>
</li>
</ul>
{% endif %}
</div>
<ul class="nav navbar-nav">
<li class="active"><a href="/">{% trans "Home" %}</a></li>
<li><a href="https://github.com/benjaoming/django-wiki" target="_blank">{% trans "About" %}</a></li>
</ul>
</div>
</div>
</div>
{% endblock %}
<div class="container" style="margin-top: 60px;">
{% if messages %}
<!-- Messages for this instance -->
{% for message in messages %}
<div class="alert alert-{{ message.tags }}">
<a class="close" data-dismiss="alert" href="#">&times;</a>
{{ message }}
</div>
{% endfor %}
{% endif %}
<!-- Reserved for breadcrumbs -->
{% block wiki_breadcrumbs %}{% endblock %}
<!-- Main page contents go here -->
{% block wiki_contents %}{% endblock %}
<footer id="wiki-footer">
<hr />
{% block wiki_footer_logo %}
<a href="https://github.com/benjaoming/django-wiki" class="pull-right"><img src="{{ STATIC_URL }}wiki/img/github_icon.png" /></a>
{% endblock %}
{% block wiki_footer_prepend %}
{% endblock %}
<p>{% blocktrans %}Powered by <a href="http://www.django-wiki.org">django-wiki</a>, an open source application under the <a href="http://www.gnu.org/licenses/quick-guide-gplv3.html">GPLv3</a> license. Let knowledge be the cure.{% endblocktrans %}</p>
<div style="clear: both"></div>
</footer>
</div>
</div> <!-- /container -->
{% endblock %}
<script src="{{ STATIC_URL }}wiki/js/jquery.min.js"></script>
<script src="{{ STATIC_URL }}wiki/js/core.js"></script>
<script src="{{ STATIC_URL }}wiki/bootstrap/js/bootstrap.min.js"></script>
<!-- Optionally enable responsive features in IE8 -->
<script src="{{ STATIC_URL }}wiki/js/respond.min.js"></script>
{% render_block "js" %}
</body>
</html>
{# Intentionally empty, to allow easy customization with no copy-paste #}
{% load sekizai_tags i18n wiki_tags %}{% load url from future %}<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>{% block wiki_pagetitle %}{% endblock %} - django-\/\/ i K |</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="description" content="">
<meta name="author" content="www.django-wiki.org">
<!-- Le styles -->
<link href="{{ STATIC_URL }}wiki/bootstrap/css/wiki-bootstrap.min.css" rel="stylesheet">
{% render_block "css" %}
<!-- Le HTML5 shim, for IE6-8 support of HTML5 elements -->
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
</head>
<body>
{% block wiki_body %}
{% block wiki_navbar %}
<div class="navbar navbar-fixed-top navbar-inverse">
<div class="container">
<!-- .navbar-toggle is used as the toggle for collapsed navbar content -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-responsive-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
{% block wiki_header_branding %}
<a class="navbar-brand" href="{% url 'wiki:root' %}">django-\/\/ i K |</a>
{% endblock %}
<div class="nav-collapse collapse navbar-responsive-collapse">
<form class="navbar-form pull-right-block-on-responsive" id="wiki-search-form" method="GET" action="{% url 'wiki:search' %}">
<div class="input-group">
<input type="search" class="form-control search-query" name="q" placeholder="{% trans "Search..." %}" />
<span class="input-group-btn">
<button class="btn btn-default" type="button">
<span class="icon-search"></span>
</button>
</span>
</div><!-- /input-group -->
</form>
<div class="pull-right-block-on-responsive">
{% if user.is_authenticated %}
<ul class="nav navbar-nav">
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">
<span class="badge notification-cnt">0</span>
{{ user }}
<b class="caret"></b>
</a>
<ul class="dropdown-menu">
<li>
<a href="{% url 'wiki:logout' %}">
<i class="icon-off"></i>
{% trans "Log out" %}
</a>
</li>
{% include "wiki/plugins/notifications/menubaritem.html" %}
</ul>
</li>
</ul>
{% else %}
<ul class="nav navbar-nav">
<li>
<a href="{% login_url as wiki_login_url %}{{ wiki_login_url }}">{% trans "Log in" %}</a>
</li>
<li>
<a href="{% url 'wiki:signup' %}">{% trans "Sign up" %}</a>
</li>
</ul>
{% endif %}
</div>
{% block wiki_header_navlinks %}
<ul class="nav navbar-nav">
<li class="active"><a href="/">{% trans "Home" %}</a></li>
<li><a href="https://github.com/benjaoming/django-wiki" target="_blank">{% trans "About" %}</a></li>
</ul>
{% endblock %}
</div>
</div>
</div>
{% endblock %}
<div class="container" style="margin-top: 60px;">
{% if messages %}
<!-- Messages for this instance -->
{% for message in messages %}
<div class="alert alert-{{ message.tags }}">
<a class="close" data-dismiss="alert" href="#">&times;</a>
{{ message }}
</div>
{% endfor %}
{% endif %}
<!-- Reserved for breadcrumbs -->
{% block wiki_breadcrumbs %}{% endblock %}
<!-- Main page contents go here -->
{% block wiki_contents %}{% endblock %}
<footer id="wiki-footer">
<hr />
{% block wiki_footer_logo %}
<a href="https://github.com/benjaoming/django-wiki" class="pull-right"><img src="{{ STATIC_URL }}wiki/img/github_icon.png" /></a>
{% endblock %}
{% block wiki_footer_prepend %}
{% endblock %}
<p>{% blocktrans %}Powered by <a href="http://www.django-wiki.org">django-wiki</a>, an open source application under the <a href="http://www.gnu.org/licenses/quick-guide-gplv3.html">GPLv3</a> license. Let knowledge be the cure.{% endblocktrans %}</p>
<div style="clear: both"></div>
</footer>
</div>
</div> <!-- /container -->
{% endblock %}
<script src="{{ STATIC_URL }}wiki/js/jquery.min.js"></script>
<script src="{{ STATIC_URL }}wiki/js/core.js"></script>
<script src="{{ STATIC_URL }}wiki/bootstrap/js/bootstrap.min.js"></script>
<!-- Optionally enable responsive features in IE8 -->
<script src="{{ STATIC_URL }}wiki/js/respond.min.js"></script>
{% render_block "js" %}
</body>
</html>
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