django-sphinx-view

Serve your Sphinx docs with Django.

Installation

Install using pip:

pip install django-sphinx-view

Then add sphinx_view to INSTALLED_APPS for template discovery:

INSTALLED_APPS = [
    ...
    "sphinx_view",
    ...
]

That’s it. You’re good to go.

Basic Usage

Build your Sphinx docs with the JSONBuilder, using make json.

Route a DocumentationView with a Path to the output JSON:

from pathlib import Path

from django.urls import path
from sphinx_view import DocumentationView

urlpatterns = [
    # ...
    path(
        "docs<path:path>",
        DocumentationView.as_view(
            json_build_dir=Path('/path/to/output/json'),
            base_template_name="docs_base.html",
        ),
        name="documentation",
    ),
    # ...
]

The json_build_dir keyword argument is required, providing the location of the rendered ouput JSON.

The base_template_name (default base.html) keyword argument allows you to provide a base template fitting your site’s layout. It should provide title, doc, and toc blocks.

You may also set a template_name (default sphinx_view/page.html) keyword arg to provide a custom template.

Enjoy.

You can subclass DocumentationView to require authentication and so add access control, and so on. You can customise the template to add other dynamic elements.

Roadmap

django-sphinx-view has two goals and one non-goal.

Goals:

  • The key DocumentationView view class to serve the rendered JSON files. Initial version is in place. I imagine small API adjustments going forwards but little else.

  • A Sphinx template bridge that will allow using the DTL when rendering the HTML docs using make html and the HTMLBuilder. This will complete the circle, so to speak, and allow building your docs to static HTML or if you don’t have the Django development server available.

The non-goal is to replace Sphinx themes in general. django-sphinx-view is about integrating Sphinx built docs into your Django site. You bring the styling, you bring the theme.