.. _quickstart:

Quickstart Guide
================

This guide assumes that you already have a `Django
<http://www.djangoproject.com/>`_ installation up and running. If this is not
the case, you should work through the `Django tutorial
<http://docs.djangoproject.com/en/dev/intro/install/#intro-install>`_ first.

You also need `Haystack <http://haystacksearch.org>`_ for searching within the
documentation.


Installation
------------

You can either install this app with `PIP <http://pypi.python.org/pypi/pip>`_ 
(or ``easy_install``):

.. sourcecode:: bash

    $ pip install django-sphinxdoc
    $ # or:
    $ easy_install django-sphinxdoc

or download and install it manually:

.. sourcecode:: bash

    $ cd where/you/put/django-sphinxdoc/
    $ python setup.py install
    
Use `this URL <http://bitbucket.org/scherfke/django-sphinxdoc/>`_ for cloning if
you want to install this app in development mode.


Setup
-----

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

    (r'^docs/', include('sphinxdoc.urls')),
    
Install the required database tables with:

.. sourcecode:: bash

    $ python manage.py syncdb

In order get Haystack working with django-sphinxdoc, you only need to executes
the steps under `Configuration
<http://docs.haystacksearch.org/dev/tutorial.html#configuration>`_ in the
Haystack tutorial (if not already done). You don’t need to create any search indexes, views or
templates yourself.
    
    
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/app/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:

.. sourcecode:: bash

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


That’s it!
----------

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