Welcome to django-knowledge’s documentation!¶

django-knowledge makes it easy to add an integrated support desk, help desk or knowledge base to your Django project with only a few lines of boilerplate code. While we give you a generic design for free, you should just as easily be able to customize the look and feel of the app if you like.

django-knowledge was developed internally for Zapier. Check out a live demo.

At a glance:¶

Turn common questions or support requests into a knowledge base.
Control who sees what with simple per object view permissions: public (everyone), private (poster & staff), or internal (only staff).
Assign questions and answers to categories for easy sorting.
Staff get moderation controls or they can use the familiar Django admin to handle support requests.
Allow anonymous questions, or require a standard Django user account (the default).
Included base templates and design with prebundled HTML and CSS.
Optionally alert users of new responses via email (or your own alert system).
BSD license.

Contents:¶

Overview¶

Django Knowledge is aiming to be a very simple knowledge base and question support engine, not entirely dissimilar to ZenKnowledge, Assistly, or HelpJuice, and to some degree StackOverflow or even UserVoice or GetSatisfaction.

Goals of django-knowledge¶

The goals of django-knowledge are simple and straightforward:

Searchable knowledge base.
A form to ask a missing question.
Staff can moderate via toolbar or Django’s admin interface.

How django-knowledge works¶

At its core, there are only a few moving parts, which keeps django-knowledge light and extensible.

Models¶

There are only three data models in django-knowledge: Question, Response and Category. As you can imagine, Question is the base model which can have an arbitrary number or Response‘s. While Response is more or less a series of comments on a Question. Question‘s can also have an arbitrary number of Categories.

Question‘s and Response‘s can each be either public, private or internal (or inheret for Response). Categories are always public.

Views¶

In the same spirit, there are only 4 user facing views: knowledge_index, knowledge_list, knowledge_thread, and knowledge_ask.

knowledge_index a general listing of popular questions plus search box
knowledge_list listing of a specific subset of questions (by tags or search term)
knowledge_thread response thread for a specific question
knowledge_moderate a passthrough for moderators to manage questions & responses
knowledge_ask form for asking a question

Templates¶

We provide default styles for the templates. You can easily embed this within your own shim/wrapper or do nothing and just roll with the wrapper we provide. Read more in the Customize section.

CSS (SASS)¶

The included generic styles are compiled via SASS’s scss. You can read more in the Customize section.

Install¶

Using pip or easy_install, which is most common for stable releases.

Using a Git checkout, recommended if you want cutting-edge features.

Using downloadable archives, useful if you don’t have pip or git.

Using pip or easy_install¶

We highly recommend using pip to install django-knowledge, the packages are regularly updated with stable releases:

pip install django-knowledge

Or, alternatively:

easy_install django-knowledge

But really, you shouldn’t do that.

Using git repositories¶

Regular development happens at our GitHub repository. Grabbing the cutting edge version might give you some extra features or fix some newly discovered bugs. We recommend not installing from the git repo unless you are actively developing django-knowledge. Please don’t use it in production (and if you do, report back what broked)!

git clone git@github.com:zapier/django-knowledge.git django-knowledge

You can add the knowledge folder inside the resulting django-knowledge to your PYTHONPATH or simply run python setup.py install to add it to your site-packages.

Using archives (tarball or zip)¶

Visit our tags page to grab the archives of both current and previous stable releases. After unzipping or untarring, you can add the knowledge folder inside the resulting django-knowledge to your PYTHONPATH or simply run python setup.py install to add it to your site-packages.

Setting up your Django project¶

First, you’ll want to add knowledge and django.contrib.markup to your INSTALLED_APPS. You may need to pip install markdown to cover the markup dependency.

INSTALLED_APPS = (
    'django.contrib.contenttypes',
    'django.contrib.comments',
    'django.contrib.sessions',
    'django.contrib.sites',
    'django.contrib.admin',

    # Your favorite apps

    'django.contrib.markup',
    'knowledge',)

Second, add url(r'^knowledge/', include('knowledge.urls')) to your urls.py.

urlpatterns = patterns('',
    url(r'^admin/', include(admin.site.urls)),

    # your url patterns

    url(r'^knowledge/', include('knowledge.urls')),
)

Third, be sure to run python manage.py syncdb or python manage.py migrate knowledge to set up the necessary database tables.

python manage.py syncdb
# or...
python manage.py migrate knowledge

Finally, follow the steps outlined in the Customize section for templates and static resources. Short version, don’t forget to run python manage.py collectstatic.

python manage.py collectstatic

Development¶

Right now django-knowledge is still under heavy development. We’re approaching the full development of this product in the manner described below.

Development pattern¶

Documentation first!

This is vitally important as we pusposefully want to create something that is a best in class application. We want django-knowledge be the premier help desk for django.
Tests next!

Again, we want people to trust this application, so tests are an absolute must. TDD is the name of the game here. 100% coverage is the goal.
Code final!

And let’s make it good code as well. pep8 and all that jazz!

Development guide¶

Please join us in making django-knowledge the best open source help desk in the world!

Documentation¶

We’re using Sphinx, so make sure you have pip install sphinx, browse on into the docs folder and run make html:

cd docs
make html

Inside docs/_build should be the rendered html. Open up docs/_build/html/index.html in your browser to take a looksy.

Editing the files is equally simple, just adhere to the reStructuredText format. I recommend using something like watch while doing documentation to auto build everything while you work:

cd docs
watch make html

Tests¶

Inside the tests directory is a bash script that runs a localized Django project that tests our application in a project context. A quick command should suffice for most basic needs:

tests/runtests.sh

Right now we’re not bundling tests inside the installed package, they are part of their own example application. All tests are found in tests/example/tests/ under split out files reflecting their location in the package.

View the coverage stats by opening up the resulting tests/reports/index.html.

Code¶

Setting up the development server is quite easy as well:

pip install -r requirements.txt
tests/syncdb.sh
tests/runserver.sh

We do use SASS (and you should too!), so you will need to follow their install docs and then run something like:

sass --watch knowledge/static/knowledge/scss:knowledge/static/knowledge/css

Please remember to run pep8 and fix any errors you see, or explan why you won’t in your commit message so we can yell at you:

pep8 knowledge

Committing¶

We work off of the master branch in our GitHub repo. Send a pull request! Tagged releases will be pushed to PyPi.

Alerts¶

django-knowledge has built in functionality that sends email alerts to subscribed users when a new response is added or accepted. Users can opt-in or out this alert at the time of posting a question or response.

Further, Users with the flag ‘is_staff’ and the permission to change questions will receive updates when a new question is added.

TODO: They can also opt-in or out after the fact.

Enabling¶

By default, alerts are disabled. to enable them, simply add to your settings.py:

KNOWLEDGE_ALERTS = True

Also ensure that the Django site framework is installed and setup properly, otherwise the default links may not work properly.

SITE_ID = 1

INSTALLED_APPS = (
    # ...
    'django.contrib.sites',
    # ...
)

Scheduling¶

By default, django-knowledge will greedily send emails via whatever email backend you have set during the request/response cycle. This is likely not desirable: we recommend using something like django-celery-email to delay the task via a queue. No further action is needed if you go this route.

Alternatively, you can specify your own email function where you can introduce your own off request functionality:

KNOWLEDGE_ALERTS_FUNCTION_PATH = 'path.to.your.own.function'

The email function should expect three keyword arguments:

target_dict - A dictionary for {'me@dom.com‘: (‘First Last (or username)’, 'me@dom.com‘)} for anonymous or {'me@dom.com‘: <User instances>}. This list is deduplicated by email address. This list is generated by including all parties involved in a thread that had checked alert, or, by list of staff User models when a new question is added.
response - A Response instance of the model triggering this alert. May be None. Only passed in when a new response is added.
question - A Question instance of the model triggering this alert. May be None. Only passed in when a new question is added.
**kwargs - It would be wise to include a blanket keyword arg catcher, we’ll likely add more things in the future, so this will keep your code from breaking.

Take a look at knowledge.signals.send_alerts for the original alert function to get an idea how it works.

Note: just to clarify: if you change the email function path setting, you will need to send the alert emails (or any other form of communication) yourself. Our builtin function will no longer act.

Templating¶

We offer three default templates used to render both the subject and message of alert emails:

django_knowledge/emails/subject.txt
django_knowledge/emails/message.txt
django_knowledge/emails/message.html

Emails are sent with both txt and html formats. Simply override these if you want to modify the defaults.

Customize¶

Since django-knowledge ships with default themes and styles, you might have to spend a little time perfecting your look. However, it should work right out of the box with minimal setup (or none!) if you don’t mind the defaults.

Templates¶

The default base template is django_knowledge/base.html which contains a single {% block knowledge_inner %} tag. This base template loads two css files from your static (see below): reset.css and base.css.

If you have your own template shim/wrapper:¶

Copy and modify django_knowledge/base.html to your own template folder. Edit it as you see fit.
Include {{ STATIC_URL }}knowledge/css/main.css for knowledge specific styling. You should purposefully leave out {{ STATIC_URL }}knowledge/css/reset.css if you don’t want us to reset your existing base styles.

If you do decide to change the base template via the KNOWLEDGE_BASE_TEMPLATE setting, your new template might look something like this:

<!doctype html>
<html lang="en">
<head>
  <title>{% block title %}{% endblock title %} | Johnny's Support Center</title>

  <link rel="stylesheet" href="{{ STATIC_URL }}css/my-own-reset.css">
  <link rel="stylesheet" href="{{ STATIC_URL }}css/my-own-style.css">

  <!-- don't forget to add me! -->
  <link rel="stylesheet" href="{{ STATIC_URL }}knowledge/css/main.css">
</head>

<body>
<div class="wrapper">

  <div class="header">
      Welcome to the Johnny's app!
  </div>

  <div class="content">
    {% block knowledge_inner %}

      {% block content %}
        <!-- your tradition content is loaded here if not django knowledge -->
      {% endblock content %}

      <!-- django knowlege is loaded here -->
    {% endblock knowledge_inner %}
  </div>

  <div class="footer">
      Copyright 2012
  </div>

</div>
</body>
</html>

That isn’t to say that our css styles will fit in perfectly, but we’ve been careful to namespace under dk-` the majority of our css classes, so conflicts should be minimal.

If you want to use the included template shim/wrapper:¶

1. Ensure static resources are loading for {{ STATIC_URL }}knowledge/css/reset.css and {{ STATIC_URL }}knowledge/css/main.css. 2. Done.

Modifying common singular sections:¶

There are two very common areas for modification:

django_knowledge/welcome.html - The support header containing the link and phrase “Welcome to our Support Center”. Simply override this locally by copying and editing templates/django_knowledge/welcome.html to your project.
django_knowledge/sidebar.html - The sidebar containing links to the homepage, ask a question and categories. Likewise, simply override this locally by copying and editing templates/django_knowledge/sidebar.html to your project.
django_knowledge/form.html - The form loops over given forms and renders them. Likewise, you can simply override this locally by copying and editing templates/django_knowledge/sidebar.html to your project.

Static¶

As long as you are using Django’s static files system, setting up static files should be as easy as python manage.py collectstatic. If not, you can always copy your files manually to a legacy MEDIA_URL and override the base template according to the above templates section.

Likewise, feel free to override the included CSS with your own rules in your own stylesheets. We’d recommend not editing the included CSS, as an update or collectstatic might overwrite them.

CSS¶

We purposefully namespace the majority of our CSS classes with dk- in order to keep them from conflicting with your existing CSS. There are two included CSS files:

reset.css - The majority of the base classes that act on body, typography, etc... This is ripped from Blueprint (though Blueprint is not a prerequisite). This should probably only be included if you aren’t using your own shim.
main.css - This contains the real meat of the styles. Most of these are namespaced so they shouldn’t affect your other styles (IE: the header/footer your shim has). However, the inverse is not true. Your styles may (and probably will) effect knowledge’s css. You’re kind of on your own here.

Performance¶

A few of the queries in the manager are a little crazy due to the need to check parent questions when responses are inherited status. We recommend ensuring the following indexes for the following fields:

DB Indexes¶

question & response `id` (Django does by default)
question & response `user_id` (Django does by default)
question & response `status` (we do this by default because query by statuses a lot!)

Email Alerts¶

If you decide to turn on email alerts, we highly recommend using something like django-celery-email or creating your own function for delayed execution with Celery, gevent, or whatever.

Settings¶

Django Knowledge has its own series of custom settings you can use to tweak its operation. As with normal Django settings, these go in settings.py, or a variant thereof.

KNOWLEDGE_ALLOW_ANONYMOUS¶

Default False. If True, users who are not logged in can ask questions. If False only registered and logged in users can ask questions.

KNOWLEDGE_AUTO_PUBLICIZE¶

Default False. If True, answered questions are automatically published. If False, staff must manually publish questions after answering.

KNOWLEDGE_FREE_RESPONSE¶

Default True. If True, any user (respecting KNOWLEDGE_ALLOW_ANONYMOUS) can respond to any question. If False, only staff or original poster may respond.

KNOWLEDGE_SLUG_URLS¶

Default True. If True, the URL for a question will have the slug from its title appended to the end and incorrect or missing slugs will result in a 301 redirect. If False, the slug is ommitted.

KNOWLEDGE_ALERTS¶

Default False. If True, we’ll send a signal to the function defined in KNOWLEDGE_ALERTS_FUNCTION_PATH and outlined in Alerts. If False we will not.

KNOWLEDGE_ALERTS_FUNCTION_PATH¶

Default knowledge.signals.send_alerts. This should be the path to a function as defined in Alerts. Depends on KNOWLEDGE_ALERTS to be active.

Links:¶

View a live demo. This is the included stock design.
Check out the documentation at ReadTheDocs.
Visit our GitHub repo and join the development!.

Screen Shots:¶

a common thread viewed by anonymous user

a common thread viewed by a moderator (staff)

Navigation

Welcome to django-knowledge’s documentation!¶

At a glance:¶

Contents:¶

Overview¶

Goals of django-knowledge¶

How django-knowledge works¶

Models¶

Views¶

Templates¶

CSS (SASS)¶

Install¶

Using pip or easy_install¶

Using git repositories¶

Using archives (tarball or zip)¶

Setting up your Django project¶

Development¶

Development pattern¶

Development guide¶

Documentation¶

Tests¶

Code¶

Committing¶

Alerts¶

Enabling¶

Scheduling¶

Templating¶

Customize¶

Templates¶

If you have your own template shim/wrapper:¶

If you want to use the included template shim/wrapper:¶

Modifying common singular sections:¶

Static¶

CSS¶

Performance¶

DB Indexes¶

Email Alerts¶

Settings¶

KNOWLEDGE_ALLOW_ANONYMOUS¶

KNOWLEDGE_LOGIN_REQUIRED¶

KNOWLEDGE_AUTO_PUBLICIZE¶

KNOWLEDGE_FREE_RESPONSE¶

KNOWLEDGE_SLUG_URLS¶

KNOWLEDGE_ALERTS¶

KNOWLEDGE_ALERTS_FUNCTION_PATH¶

Links:¶

Screen Shots:¶

Table Of Contents

Quick search

Navigation