# django-docutils · [![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 (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+
[![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)
Raw data
{
"_id": null,
"home_page": null,
"name": "django-docutils",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "django, docutils, reST, reStructuredText, rst",
"author": null,
"author_email": "Tony Narlock <tony@git-pull.com>",
"download_url": "https://files.pythonhosted.org/packages/bd/7d/ec259e916911507005a39631660333f7ab990aa865f612dc483d694f87d9/django_docutils-0.28.0.tar.gz",
"platform": null,
"description": "# django-docutils · [![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)\n\ndocutils (a.k.a. reStructuredText / rst / reST) support for Django.\n\n## Quickstart\n\nInstall django-docutils:\n\n```console\n$ pip install django-docutils\n```\n\nNext, add `django_docutils` to your `INSTALLED_APPS` in your settings file:\n\n```python\nINSTALLED_APPS = [\n # ... your default apps,\n 'django_docutils'\n]\n```\n\n## Template tag\n\nIn your template:\n\n```django\n{% load django_docutils %}\n{% rst %}\n# hey\n# how's it going\nA. hows\nB. it\n\nC. going\nD. today\n\n**hi**\n*hi*\n{% endrst %}\n```\n\n## Template filter\n\nIn your template:\n\n```django\n{% load django_docutils %}\n{% filter rst %}\n# hey\n# how's it going\nA. hows\nB. it\n\nC. going\nD. today\n\n**hi**\n*hi*\n{% endfilter %}\n```\n\n## Template engine (class-based view)\n\nYou can also use a class-based view to render reStructuredText (reST).\n\nIf you want to use reStructuredText as a django template engine, `INSTALLED_APPS` _isn't_ required,\ninstead you add this to your `TEMPLATES` variable in your settings:\n\n```python\nTEMPLATES = [\n # ... Other engines\n {\n \"NAME\": \"docutils\",\n \"BACKEND\": \"django_docutils.template.DocutilsTemplates\",\n \"DIRS\": [],\n \"APP_DIRS\": True,\n }\n]\n```\n\nNow django will be able to scan for .rst files and process them. In your view:\n\n```python\nfrom django_docutils.views import DocutilsView\n\nclass HomeView(DocutilsView):\n template_name = 'base.html'\n rst_name = 'home.rst'\n```\n\n# Settings\n\n```python\n# Optional, automatically maps roles, directives and transformers\nDJANGO_DOCUTILS_LIB_RST = {\n \"docutils\": {\n \"raw_enabled\": True,\n \"strip_comments\": True,\n \"initial_header_level\": 2,\n },\n \"roles\": {\n \"local\": {\n \"gh\": \"django_docutils.lib.roles.github.github_role\",\n \"twitter\": \"django_docutils.lib.roles.twitter.twitter_role\",\n \"email\": \"django_docutils.lib.roles.email.email_role\",\n }\n },\n \"directives\": {\n \"code-block\": \"django_docutils.lib.directives.code.CodeBlock\",\n }\n}\n\n# Optional\nDJANGO_DOCUTILS_LIB_TEXT = {\n \"uncapitalized_word_filters\": [\"project.my_module.my_capitalization_fn\"]\n}\n```\n\n## More information\n\n- Python 3.9+\n- Django 4.2+\n\n[![Docs](https://github.com/tony/django-docutils/workflows/docs/badge.svg)](https://github.com/tony/django-docutils/actions?query=workflow%3A%22Docs%22)\n[![Build Status](https://github.com/tony/django-docutils/workflows/tests/badge.svg)](https://github.com/tony/django-docutils/actions?query=workflow%3A%22tests%22)\n[![Code Coverage](https://codecov.io/gh/tony/django-docutils/branch/master/graph/badge.svg)](https://codecov.io/gh/tony/django-docutils)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Docutils (a.k.a. reStructuredText, reST, RST) support for django.",
"version": "0.28.0",
"project_urls": null,
"split_keywords": [
"django",
" docutils",
" rest",
" restructuredtext",
" rst"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e3ea525caeb819c4ab96126ef19be482e21b658c3ed2fdf281f8b2ba22d30e8d",
"md5": "e49861e45a46a8e4740f7ee930ea31fa",
"sha256": "57a0f79c0d8b27e01319fb4c25eff80170329cd9ddec3a89e284e19564d570d7"
},
"downloads": -1,
"filename": "django_docutils-0.28.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e49861e45a46a8e4740f7ee930ea31fa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 44657,
"upload_time": "2024-12-21T01:43:34",
"upload_time_iso_8601": "2024-12-21T01:43:34.640235Z",
"url": "https://files.pythonhosted.org/packages/e3/ea/525caeb819c4ab96126ef19be482e21b658c3ed2fdf281f8b2ba22d30e8d/django_docutils-0.28.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bd7dec259e916911507005a39631660333f7ab990aa865f612dc483d694f87d9",
"md5": "ce0123558ae466d58fe5a0afc71d73c4",
"sha256": "a5f1f670aedef7dc28b1317968ccb7b1a8c4863b4624b16ef065e63b192cd58b"
},
"downloads": -1,
"filename": "django_docutils-0.28.0.tar.gz",
"has_sig": false,
"md5_digest": "ce0123558ae466d58fe5a0afc71d73c4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 132855,
"upload_time": "2024-12-21T01:43:37",
"upload_time_iso_8601": "2024-12-21T01:43:37.130521Z",
"url": "https://files.pythonhosted.org/packages/bd/7d/ec259e916911507005a39631660333f7ab990aa865f612dc483d694f87d9/django_docutils-0.28.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-21 01:43:37",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "django-docutils"
}