Welcome to django-sphinxdoc’s documentation!¶
Contents:
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/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:
(r'^docs/', include('sphinxdoc.urls')),
Install the required database tables with:
$ python manage.py migrate
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.
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.pyis 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:
$ 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:
$ python manage.py updatedoc <project-slug>
That’s it!¶
You can now find the application’s documentation under /docs/<slug>/.
Auto-build JSON files on hg pull/push¶
If you use Mercurial (hg), you can update your documentation automatically each time you push to your web server (or if you pull from another server to your web server).
To do that, open your repository’s .hg/hgrc in your favorite editor and add
the following lines to it:
[hooks]
changegroup = /path/to/your/python path/to/manage.py updatedoc -b <project>
Now, each time the repository is modified via a pull or push command, the documentation on your Django site will be updated automatically.
Change your documentation’s appearance¶
The templates for django-sphinxdoc consist of of three top-level div
with the following classes:
pagination-top- The upper pagination bar with breadcrumbs and links to the previous and next section.
sphinx- The stuff generated by
Sphinx. pagination-bottom- Like the upper pagination bar, but also contains the build date.
The following examples demonstrate how you can change the appearance of your documentation.
The “¶” sign after headings¶
To only show the headings’ “¶” sign if you hover above the heading, add something like this to your CSS:
#content .sphinx a.headerlink {
font-size: 0.8em;
padding: 0 4px 0 4px;
text-decoration: none;
visibility: hidden;
}
#content .sphinx *:hover > a.headerlink { visibility: visible; }
Changing font sizes for headings¶
Another style-problem for your site might be, that the Sphinx stuff starts with
<h1> as top level heading, but that your site uses <h1> for the site
title and <h2> as top level content heading.
I haven’t found a way to modify Sphinx’ behavior and make it use <h2>. To
work around this, you can just change the font sizes of the Sphinx headings, so
that Sphinx’ <h1> matches your <h2>:
h1 { font-size: 40px; } /* This is your blog title */
h2 { font-size: 22px; } /* This is used for page and post titles */
h3 { font-size: 18px; }
/* Changes for Sphinx */
#content .sphinx h1 { font-size: 22px; }
#content .sphinx h2 { font-size: 18px; }
Changing the appearance of references and class names¶
You can also change the appearance of references of class and method descriptions, e.g.:
#content .sphinx a.reference { text-decoration: none; }
#content .sphinx a.reference tt.literal {
border-bottom-width: 1px;
border-bottom-style: dotted;
}
#content .sphinx a.reference em { font-style: normal; }
/* Smaller desc (default was 14px) and bold class name */
#content .sphinx .descclassname { font-size: 13px; }
#content .sphinx .descname { font-weight: bold; }
Other elements¶
It’s very easy to change the style of other elements. Just search for the
elements and their CSS class names in the HTML output and add them to your CSS
file. Remember to precede each style definition with #content .sphinx to
avoid side effects to non-Sphinx stuff.