Quickstart Guide

This guide assumes that you already have a Django installation up and running. If this is not the case, you should work through the Django tutorial first.

You also need Haystack for searching within the documentation.

Installation

Just use PIP:

$ pip install django-sphinxdoc

If you want the lates development version, isntall it from Bitbucket:

$ pip install https://ssc@bitbucket.org/sscherfke/django-sphinxdoc
$ # or
$ hg clone ssh://hg@bitbucket.org/sscherfke/django-sphinxdoc
$ pip install -e django-sphinxdoc

Setup

Add 'sphinxdoc' to your INSTALLED_APPS in your settings.py and add the following line to your project’s urls.py:

(r'^docs/', include('sphinxdoc.urls')),

Install the required database tables with:

$ python manage.py migrate

In order get Haystack working with django-sphinxdoc, you only need to executes the steps under Configuration in the Haystack tutorial (if not already done). You don’t need to create any search indexes, views or templates yourself.

Optional Settings

Optional sphinxdoc settings in your settings.py.

SPHINXDOC_CACHE_MINUTES:
Sets the length of the cache duration for sphinxdoc pages in minutes. If not set, defaults to 5 minutes. For caching to be active, you must enable Django’s cache framework
SPHINXDOC_BUILD_DIR:
Sets the name of target directory (within the project root) for the sphinx builder and the sphinxdoc updater. If not set, defaults to _build.
SPHINXDOC_PROTECTED_PROJECTS
A mapping of project slugs to lists of permissions indicating that users are required to log in and have the list of permissions to view the documented project. An empty list will just require a log in.
SPHINXDOC_BASE_TEMPLATE
Overrides the default sphinxdoc base template (‘base.html’).

Add a project

Django-sphinxdoc adds the application Sphinxdoc with the Project and Document models to your admin panel. Create a new project and fill out these fields:

Name:
The name of the documented project
Slug:
A sluggified version of the project name; will be generated automatically
Path:
A file system path to the Sphinx project (where Sphinx’ conf.py is located), e.g.: /path/to/project/docs

Build & import the documentation

You need to build JSON files from your documentation and import their content into your site’s database. Django-sphinxdoc provides a management command to help you with that:

$ python manage.py updatedoc -b <project-slug>

Note that the -b option requires Sphinx to be installed. If you wish to build your documentation elsewhere, you can use the same command without the build option to update the database with the pre-built files:

$ python manage.py updatedoc <project-slug>

That’s it!

You can now find the application’s documentation under /docs/<slug>/.