Skip to main content

Documentation Utilities (Docutils, reStructuredText) for django.)

Project description

Python Package Docs Build Status Code Coverage License

django-docutils, docutils (reStructuredText) support for Django


The full documentation is at


Install django-docutils:

pip install django-docutils

# if fetching favicons
pip install django-docutils[favicon]

# intersphinx support
pip install django-docutils[intersphinx]

# both
pip install django-docutils[favicon,intersphinx]

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,

Then in your template:

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

C. going
D. today

{% 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

BASED_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': '',
    'font_awesome': {  # Transformer to inject <em class="<class>"></em>
        'url_patterns': {
            r'.**': 'fab fa-github',
            r'.**': 'fab fa-twitter',
            r'.**': 'fab fa-amazon',
            r'.**': 'fab fa-amazon',
            r'.**': 'fab fa-hacker-news',
            r'.**': 'fab fa-leanpub',
            r'.**': 'fab fa-python',
            r'.**': 'fab fa-python',
            r'.**': 'fab fa-python',
            r'.**': 'fab fa-wikipedia',
            r'((rtfd|readthedocs).)*$': 'fab fa-books',
            r'^mailto:.*': 'fas fa-envelope',
            r'((?!|localhost).)*$': 'fas fa-external-link',

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

BASED_ADS = {  # If injecting ads
    'AMAZON_AD_CODE': """
    <script type="text/javascript">
    amzn_assoc_placement = "adunit0";
    amzn_assoc_search_bar = "true";
    amzn_assoc_tracking_id = "mytracking-20";
    amzn_assoc_search_bar_position = "bottom";
    amzn_assoc_ad_mode = "search";
    amzn_assoc_ad_type = "smart";
    amzn_assoc_marketplace = "amazon";
    amzn_assoc_region = "US";
    amzn_assoc_title = "You may be interested in";
    amzn_assoc_default_search_phrase = "{keyword}";
    amzn_assoc_default_category = "All";
    amzn_assoc_linkid = "6efef5538142e4a4031b04de66b6e804";
    <script src="//"></script>
        '<script src="//'
    'GOOGLE_AD_CODE': """
    <script async src="//">
    <ins class="adsbygoogle"
         style="display:block; text-align:center;"
         (adsbygoogle = window.adsbygoogle || []).push({});

Project details

Download files

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

Files for django-docutils, version 0.5.1
Filename, size File type Python version Upload date Hashes
Filename, size django_docutils-0.5.1-py3-none-any.whl (99.3 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size django-docutils-0.5.1.tar.gz (68.2 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page