.. _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.


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

This app requires `Setuptools <http://pypi.python.org/pypi/setuptools>`_ for
installation.

You can either `download a stable version
<http://bitbucket.org/scherfke/django-sphinxdoc/downloads/>`_ or use the latest
version from the `repository <http://bitbucket.org/scherfke/django-sphinxdoc/src/>`_.

If you downloaded the stable version, unpack it and open a terminal. Change to
the directory that contains *django-sphinxdoc’s* ``setup.py`` and execute it as
follows:

.. sourcecode:: bash

    $ cd where/you/put/django-sphinxdoc/
    $ sudo python setup.py install
    
If you want the bleeding edge, clone the repository and install it in
development mode. This will create just a link in your ``site packages`` that
points to your local repository:

.. sourcecode:: bash

    $ hg clone http://bitbucket.org/scherfke/django-sphinxdoc/
    $ cd django-sphinxdoc/
    $ sudo python setup.py develop
    
With this done, all you need to do to upgrade your installation of
*django-sphinxdoc* is to type:

.. sourcecode:: bash

   $ hg pull -u


Setup
-----

Add ``'sphinxdoc'`` to your ``INSTALLED_APPS`` within 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 table with:

.. sourcecode:: bash

    python manage.py syncdb
    
    
Add an application
------------------

If you visit your project’s admin panel, you’ll find the new application
*Sphinxdoc* with the *App* model. If you add a new app, you’ll need to fill
three form fields:

Name:
    The name of the documented application
    
Slug:
    A sluggified version of the application name; will be generated
    automatically

Path:
    A file system path to the JSON files generated by Sphinx including
    ``_build/json/``, e.g.: ``/path/to/app/doc/_build/json/``


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

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

You may want to read:

* :ref:`autobuild`
* :ref:`change_appearance`
