Sphinx

The Sphinx-Django section describes how to convert ones Sphinx sources into an intermediate target that is embeddable within Django. This section describes how to embed this intermediate source into ones pages served by Django.

Configuration

Given a standard Django project structure :

Website Web Application 
PROJECT
 +- WEBAPP
 |   +- settings.py
 |   +- views.py
 |   +- urls.py
 |   +- ...
 +- templates
     +- DOCUMENTATION

PROJECT
 +- WEBAPP
     +- templates
         +- DOCUMENTATION
     +- settings.py
     +- views.py
     +- urls.py
     +- ...

Where WEBAPP is either the website or a web application created by django-admin. Perform the following operations from within the PROJECT root.

Builds ones documentation, setting TARGET to templates/DOCUMENTATION for a website, :

sphinx-build -D html_theme=sphinx_django [OPTIONS] SOURCE templates/DOCUMENTATION [FILES...]

or WEBAPP/templates/DOCUMENTATION for a web application

sphinx-build -D html_theme=sphinx_django [OPTIONS] SOURCE WEBAPP/templates/DOCUMENTATION [FILES...]

Include the templates folder as a source for templates for the website :

or include the web application within ones site configuration

Create a base template named base.sphinx.html (Click to download). Provide a view function

and register it under the url path /documents/.

If your setup is for a web application be sure to link across to it from the website.

Multiple sets of documentaion can be hosted provided one replaces WEBAPP and DOCUMENATION uniquely for each such application.