Quickstart Guide — django-sphinxdoc 1.2.0 documentation

### Navigation

- index
- modules |
- next |
- previous |
- django-sphinxdoc 1.2.0 documentation »

# 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/ssc/django-sphinxdoc
    $ # or
    $ hg clone ssh://hg@bitbucket.org/ssc/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 syncdb

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.

## 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 an management command to help you with that:

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

## That’s it!

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

### Navigation

- index
- modules |
- next |
- previous |
- django-sphinxdoc 1.2.0 documentation »