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

Just use `PIP <http://pypi.python.org/pypi/pip>`_:

.. sourcecode:: bash

    $ pip install django-sphinxdoc

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

.. sourcecode:: bash

    $ 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``:

.. sourcecode:: python

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

Install the required database tables with:

.. sourcecode:: bash

    $ python manage.py migrate

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.


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 <https://docs.djangoproject.com/en/dev/topics/cache/>`_

``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:

.. sourcecode:: bash

    $ 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:

.. sourcecode:: bash

    $ python manage.py updatedoc <project-slug>


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

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