django-docutils 0.13.4

Documentation Utilities (Docutils, reStructuredText) for django.

django-docutils ·

django-docutils, docutils (reStructuredText) support for Django

Quickstart

Install django-docutils:

$ pip install django-docutils

Template filter

If you want to use the template filter, add it to your INSTALLED_APPS in your settings file:

INSTALLED_APPS = [ # ... your default apps,
    'django_docutils'
]

Then in your template:

{% load django_docutils %}
{% filter restructuredtext %}
# hey
# how's it going
A. hows
B. it

C. going
D. today

**hi**
*hi*
{% endfilter %}

Template engine (class-based view)

You can also use a class-based view to render restructuredtext.

If you want to use reStructuredText as a django template engine, INSTALLED_APPS isn't required, instead you add this to your TEMPLATES variable in your settings:

TEMPLATES = [ # .. your default engines
{
    'NAME': 'docutils',
    'BACKEND': 'django_docutils.engines.Docutils',
    'DIRS': [],
    'APP_DIRS': True,
}]

Now django will be able to scan for .rst files and process them. In your view:

from django_docutils.views import DocutilsView

class HomeView(DocutilsView):
    template_name = 'base.html'
    rst_name = 'home.rst'

Settings

DJANGO_DOCUTILS_LIB_RST = {  # Optional, automatically maps roles, directives and transformers
    'docutils': {
        'raw_enabled': True,
        'strip_comments': True,
        'initial_header_level': 2,
    },
    'roles': {
        'local': {
            'gh': 'django_docutils.lib.roles.github.github_role',
            'twitter': 'django_docutils.lib.roles.twitter.twitter_role',
            'email': 'django_docutils.lib.roles.email.email_role',
        }
    },
    'font_awesome': {  # Transformer to inject <em class="<class>"></em>
        'url_patterns': {
            r'.*github.com.*': 'fab fa-github',
            r'.*twitter.com.*': 'fab fa-twitter',
            r'.*news.ycombinator.com*': 'fab fa-hacker-news',
            r'.*leanpub.com.*': 'fab fa-leanpub',
            r'.*python.org.*': 'fab fa-python',
            r'.*pypi.org.*': 'fab fa-python',
            r'.*djangoproject.com.*': 'fab fa-python',
            r'.*wikipedia.org.*': 'fab fa-wikipedia',
            r'((rtfd|readthedocs).)*$': 'fab fa-books',
            r'^mailto:.*': 'fas fa-envelope',
            r'((?!mywebsite.com|localhost).)*$': 'fas fa-external-link',
        }
    },
}

DJANGO_DOCUTILS_LIB_TEXT = {  # Optional
    'uncapitalized_word_filters': ['project.my_module.my_capitalization_fn']
}

More information

• Python 3.8+
• Django 3.2+