https://github.com/tony/django-docutils
Docutils (a.k.a. reStructuredText, reST, RST) support for django
https://github.com/tony/django-docutils
django docutils python restructuredtext rst sphinx-doc sphinx-extension
Last synced: 6 months ago
JSON representation
Docutils (a.k.a. reStructuredText, reST, RST) support for django
- Host: GitHub
- URL: https://github.com/tony/django-docutils
- Owner: tony
- License: mit
- Created: 2015-06-20T08:25:49.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2025-07-20T21:07:59.000Z (7 months ago)
- Last Synced: 2025-07-21T07:31:34.360Z (7 months ago)
- Topics: django, docutils, python, restructuredtext, rst, sphinx-doc, sphinx-extension
- Language: Python
- Homepage: https://django-docutils.git-pull.com/
- Size: 2.81 MB
- Stars: 11
- Watchers: 2
- Forks: 2
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES
- License: LICENSE
Awesome Lists containing this project
README
# django-docutils · [](https://pypi.org/project/django-docutils/) [](https://github.com/tony/django-docutils/blob/master/LICENSE)
docutils (a.k.a. reStructuredText / rst / reST) support for Django.
## 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 %}
# hey
# how's it going
A. hows
B. it
C. going
D. today
**hi**
*hi*
{% endrst %}
```
## Template filter
In your template:
```django
{% 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:
```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": {
"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.9+
- Django 4.2+
[](https://github.com/tony/django-docutils/actions?query=workflow%3A%22Docs%22)
[](https://github.com/tony/django-docutils/actions?query=workflow%3A%22tests%22)
[](https://codecov.io/gh/tony/django-docutils)