Metadata-Version: 2.4
Name: django-docutils
Version: 0.30.0
Summary: Docutils (a.k.a. reStructuredText, reST, RST) support for django.
Author-email: Tony Narlock <tony@git-pull.com>
License: MIT
License-File: LICENSE
Keywords: django,docutils,reST,reStructuredText,rst
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: <4.0,>=3.10
Requires-Dist: django>=4.2
Requires-Dist: docutils
Requires-Dist: pygments<3
Provides-Extra: pytz
Requires-Dist: pytz; extra == 'pytz'
Description-Content-Type: text/markdown

# django-docutils &middot; [![Python Package](https://img.shields.io/pypi/v/django-docutils.svg)](https://pypi.org/project/django-docutils/) [![License](https://img.shields.io/github/license/tony/django-docutils.svg)](https://github.com/tony/django-docutils/blob/master/LICENSE)

[docutils](https://docutils.sourceforge.io/) (a.k.a.
[reStructuredText](https://docutils.sourceforge.io/rst.html) / rst / reST)
support for Django.

Documentation: <https://django-docutils.git-pull.com/>

django-docutils turns off docutils features that are risky on the web — raw
HTML pass-through, file inclusion, and local `docutils.conf` lookup — and
filters unsafe link schemes from rendered output. That reduces risk; it does
not make untrusted markup safe. If people can submit their own
reStructuredText or Markdown to your site (comments, profiles, CMS fields),
read the [Security topic](https://django-docutils.git-pull.com/topics/security.html)
first.

## Quickstart

Install django-docutils:

```console
$ pip install django-docutils
```

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

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

## Template tag

In your template:

```django
{% load django_docutils %}
{% rst %}
Welcome
=======

Write `reStructuredText <https://docutils.sourceforge.io/rst.html>`_ with
links, **bold** text, and highlighted code:

.. code-block:: python

   print("hello")
{% endrst %}
```

## Template filter

In your template:

```django
{% load django_docutils %}
{% filter rst %}
Welcome
=======

Write `reStructuredText <https://docutils.sourceforge.io/rst.html>`_ with
links, **bold** text, and highlighted code:

.. code-block:: python

   print("hello")
{% 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:

```python
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:

```python
from django_docutils.views import DocutilsView

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

# Settings

```python
# Optional, automatically maps roles, directives and transformers
DJANGO_DOCUTILS_LIB_RST = {
    "docutils": {
        "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"]
}
```

For trusted static RST only — never for user-submitted content — docutils
features that the default rendering disables can be re-enabled with an
explicit opt-in
([Security topic](https://django-docutils.git-pull.com/topics/security.html),
[docutils security guide](https://docutils.sourceforge.io/docs/howto/security.html)):

```python
DJANGO_DOCUTILS_LIB_RST = {
    "allow_unsafe_docutils_settings": True,
    "docutils": {
        "raw_enabled": True,
        "file_insertion_enabled": True,
    },
}
```

## More information

- Python 3.10+
- Django 4.2+
- [Documentation](https://django-docutils.git-pull.com/) ·
  [Quickstart](https://django-docutils.git-pull.com/quickstart.html) ·
  [Security](https://django-docutils.git-pull.com/topics/security.html) ·
  [FAQ](https://django-docutils.git-pull.com/topics/faq.html)
- New to the ecosystem? [What is docutils?](https://django-docutils.git-pull.com/topics/what_is_docutils.html)
  untangles docutils, reStructuredText, Sphinx, and Markdown.
- [reStructuredText primer](https://docutils.sourceforge.io/docs/user/rst/quickstart.html)
  and [quick reference](https://docutils.sourceforge.io/docs/user/rst/quickref.html)
  from the docutils project.

[![Docs](https://github.com/tony/django-docutils/workflows/docs/badge.svg)](https://github.com/tony/django-docutils/actions?query=workflow%3A%22Docs%22)
[![Build Status](https://github.com/tony/django-docutils/workflows/tests/badge.svg)](https://github.com/tony/django-docutils/actions?query=workflow%3A%22tests%22)
[![Code Coverage](https://codecov.io/gh/tony/django-docutils/branch/master/graph/badge.svg)](https://codecov.io/gh/tony/django-docutils)
