Skip to main content

Docutils (a.k.a. reStructuredText, reST, RST) support for django.

Project description

django-docutils · Python Package License

docutils (a.k.a. reStructuredText / rst / reST) support for Django.

Quickstart

Install django-docutils:

$ pip install django-docutils

Next, add django_docutils to your INSTALLED_APPS in your settings file:

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

Template tag

In your template:

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

C. going
D. today

**hi**
*hi*
{% endrst %}

Template filter

In your template:

{% load django_docutils %}
{% filter rst %}
# 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 (reST).

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 = [
    # ... Other engines
    {
        "NAME": "docutils",
        "BACKEND": "django_docutils.template.DocutilsTemplates",
        "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

# Optional, automatically maps roles, directives and transformers
DJANGO_DOCUTILS_LIB_RST = {
    "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",
        }
    },
    "directives": {
        "code-block": "django_docutils.lib.directives.code.CodeBlock",
    }
}

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

More information

  • Python 3.8+
  • Django 3.2+

Docs Build Status Code Coverage

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_docutils-0.26.0.tar.gz (33.6 kB view hashes)

Uploaded Source

Built Distribution

django_docutils-0.26.0-py3-none-any.whl (44.8 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page