# exc Source: https://django-docutils.git-pull.com/api/exc/ (api_exc)= # `exc` ```{eval-rst} .. automodule:: django_docutils.exc ``` --- # API Reference Source: https://django-docutils.git-pull.com/api/ (api)= # API Reference :::{seealso} {ref}`Quickstart `. ::: ::::{grid} 1 1 2 2 :gutter: 2 2 3 3 :::{grid-item-card} Exceptions :link: exc :link-type: doc Exception definitions for django-docutils. ::: :::{grid-item-card} Views :link: views :link-type: doc `DocutilsView` and response classes. ::: :::{grid-item-card} Lib :link: lib/index :link-type: doc Publisher, roles, directives, writers, and transforms. ::: :::{grid-item-card} Template Engine :link: template :link-type: doc `DocutilsTemplates` backend for Django. ::: :::{grid-item-card} Template Tags :link: templatetags/index :link-type: doc `{% rst %}` tag and `rst` filter internals. ::: :::: ```{toctree} :maxdepth: 1 :hidden: exc views lib/index template templatetags/index ``` --- # lib.directives.code Source: https://django-docutils.git-pull.com/api/lib/directives/code/ (api_lib_directives_code)= # `lib.directives.code` ```{eval-rst} .. automodule:: django_docutils.lib.directives.code :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib.directives Source: https://django-docutils.git-pull.com/api/lib/directives/ (api_lib_directives)= # `lib.directives` ```{toctree} :maxdepth: 1 code registry ``` ```{eval-rst} .. automodule:: django_docutils.lib.directives :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib.directives.registry Source: https://django-docutils.git-pull.com/api/lib/directives/registry/ (api_lib_directives_registry)= # `lib.directives.registry` ```{eval-rst} .. automodule:: django_docutils.lib.directives.registry :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib Source: https://django-docutils.git-pull.com/api/lib/ (api_lib)= # `lib` ```{toctree} :maxdepth: 1 directives/index metadata/index publisher roles/index settings text transforms/index utils views writers ``` --- # lib.metadata.extract Source: https://django-docutils.git-pull.com/api/lib/metadata/extract/ (api_lib_metadata_extract)= # `lib.metadata.extract` ```{eval-rst} .. automodule:: django_docutils.lib.metadata.extract :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib.metadata Source: https://django-docutils.git-pull.com/api/lib/metadata/ (api_lib_metadata)= # `lib.metadata` ```{toctree} :maxdepth: 1 extract process processors ``` ```{eval-rst} .. automodule:: django_docutils.lib.metadata :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib.metadata.process Source: https://django-docutils.git-pull.com/api/lib/metadata/process/ (api_lib_metadata_process)= # `lib.metadata.process` ```{eval-rst} .. automodule:: django_docutils.lib.metadata.process :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib.metadata.processors Source: https://django-docutils.git-pull.com/api/lib/metadata/processors/ (api_lib_metadata_processors)= # `lib.metadata.processors` ```{eval-rst} .. automodule:: django_docutils.lib.metadata.processors :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib.publisher Source: https://django-docutils.git-pull.com/api/lib/publisher/ (api_lib_publisher)= # `lib.publisher` ```{eval-rst} .. automodule:: django_docutils.lib.publisher :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib.roles.common Source: https://django-docutils.git-pull.com/api/lib/roles/common/ (api_lib_roles_common)= # `lib.roles.common` ```{eval-rst} .. automodule:: django_docutils.lib.roles.common :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib.roles.email Source: https://django-docutils.git-pull.com/api/lib/roles/email/ (api_lib_roles_email)= # `lib.roles.email` ```{eval-rst} .. automodule:: django_docutils.lib.roles.email :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib.roles.file Source: https://django-docutils.git-pull.com/api/lib/roles/file/ (api_lib_roles_file)= # `lib.roles.file` ```{eval-rst} .. automodule:: django_docutils.lib.roles.file :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib.roles.github Source: https://django-docutils.git-pull.com/api/lib/roles/github/ (api_lib_roles_github)= # `lib.roles.github` ```{eval-rst} .. automodule:: django_docutils.lib.roles.github :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib.roles.hackernews Source: https://django-docutils.git-pull.com/api/lib/roles/hackernews/ (api_lib_roles_hackernews)= # `lib.roles.hackernews` ```{eval-rst} .. automodule:: django_docutils.lib.roles.hackernews :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib.roles Source: https://django-docutils.git-pull.com/api/lib/roles/ (api_lib_roles)= # `lib.roles` ## Core ```{toctree} :maxdepth: 1 common registry types ``` ## Custom roles ```{toctree} :maxdepth: 1 email file github hackernews kbd leanpub pypi readthedocs twitter url wikipedia ``` ```{eval-rst} .. automodule:: django_docutils.lib.roles :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib.roles.kbd Source: https://django-docutils.git-pull.com/api/lib/roles/kbd/ (api_lib_roles_kbd)= # `lib.roles.kbd` ```{eval-rst} .. automodule:: django_docutils.lib.roles.kbd :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib.roles.leanpub Source: https://django-docutils.git-pull.com/api/lib/roles/leanpub/ (api_lib_roles_leanpub)= # `lib.roles.leanpub` ```{eval-rst} .. automodule:: django_docutils.lib.roles.leanpub :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib.roles.pypi Source: https://django-docutils.git-pull.com/api/lib/roles/pypi/ (api_lib_roles_pypi)= # `lib.roles.pypi` ```{eval-rst} .. automodule:: django_docutils.lib.roles.pypi :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib.roles.readthedocs Source: https://django-docutils.git-pull.com/api/lib/roles/readthedocs/ (api_lib_roles_readthedocs)= # `lib.roles.readthedocs` ```{eval-rst} .. automodule:: django_docutils.lib.roles.readthedocs :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib.roles.registry Source: https://django-docutils.git-pull.com/api/lib/roles/registry/ (api_lib_roles_registry)= # `lib.roles.registry` ```{eval-rst} .. automodule:: django_docutils.lib.roles.registry :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib.roles.twitter Source: https://django-docutils.git-pull.com/api/lib/roles/twitter/ (api_lib_roles_twitter)= # `lib.roles.twitter` ```{eval-rst} .. automodule:: django_docutils.lib.roles.twitter :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib.roles.types Source: https://django-docutils.git-pull.com/api/lib/roles/types/ (api_lib_roles_types)= # `lib.roles.types` ```{eval-rst} .. automodule:: django_docutils.lib.roles.types :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib.roles.url Source: https://django-docutils.git-pull.com/api/lib/roles/url/ (api_lib_roles_url)= # `lib.roles.url` ```{eval-rst} .. automodule:: django_docutils.lib.roles.url :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib.roles.wikipedia Source: https://django-docutils.git-pull.com/api/lib/roles/wikipedia/ (api_lib_roles_wikipedia)= # `lib.roles.wikipedia` ```{eval-rst} .. automodule:: django_docutils.lib.roles.wikipedia :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib.settings Source: https://django-docutils.git-pull.com/api/lib/settings/ (api_lib_settings)= # `lib.settings` ```{eval-rst} .. automodule:: django_docutils.lib.settings :members: :private-members: :show-inheritance: :undoc-members: :member-order: bysource ``` --- # lib.text Source: https://django-docutils.git-pull.com/api/lib/text/ (api_lib_text)= # `lib.text` ```{eval-rst} .. automodule:: django_docutils.lib.text :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib.roles.transforms.code Source: https://django-docutils.git-pull.com/api/lib/transforms/code/ (api_lib_transforms_code)= # `lib.roles.transforms.code` ```{eval-rst} .. automodule:: django_docutils.lib.transforms.code ``` --- # lib.transforms Source: https://django-docutils.git-pull.com/api/lib/transforms/ (api_lib_transforms)= # `lib.transforms` ```{toctree} :maxdepth: 1 code toc ``` ```{eval-rst} .. automodule:: django_docutils.lib.transforms :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib.roles.transforms.toc Source: https://django-docutils.git-pull.com/api/lib/transforms/toc/ (api_lib_transforms_toc)= # `lib.roles.transforms.toc` ```{eval-rst} .. automodule:: django_docutils.lib.transforms.toc ``` --- # lib.utils Source: https://django-docutils.git-pull.com/api/lib/utils/ (api_lib_utils)= # `lib.utils` ```{eval-rst} .. automodule:: django_docutils.lib.utils :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib.views Source: https://django-docutils.git-pull.com/api/lib/views/ (api_lib_views)= # `lib.views` ```{eval-rst} .. automodule:: django_docutils.lib.views :members: :private-members: :show-inheritance: :member-order: bysource ``` --- # lib.writers Source: https://django-docutils.git-pull.com/api/lib/writers/ (api_lib_writers)= # `lib.writers` ```{eval-rst} .. automodule:: django_docutils.lib.writers :members: :private-members: :show-inheritance: :undoc-members: :member-order: bysource ``` --- # template Source: https://django-docutils.git-pull.com/api/template/ (api_template)= # `template` ```{eval-rst} .. automodule:: django_docutils.template ``` --- # templatetags.django_docutils Source: https://django-docutils.git-pull.com/api/templatetags/django_docutils/ (api_templatetags_django_docutils)= # `templatetags.django_docutils` ```{eval-rst} .. automodule:: django_docutils.templatetags.django_docutils ``` --- # templatetags Source: https://django-docutils.git-pull.com/api/templatetags/ (api_templatetags)= # `templatetags` ```{toctree} :maxdepth: 1 django_docutils ``` ```{eval-rst} .. automodule:: django_docutils.templatetags ``` --- # views Source: https://django-docutils.git-pull.com/api/views/ (api_views)= # `views` ```{eval-rst} .. automodule:: django_docutils.views ``` --- # Changelog Source: https://django-docutils.git-pull.com/history/ (history)= ```{include} ../CHANGES ``` --- # django-docutils Source: https://django-docutils.git-pull.com/ (index)= # django-docutils Docutils (reStructuredText) support for Django templates, views, and template engines. ::::{grid} 1 1 2 2 :gutter: 2 2 3 3 :::{grid-item-card} Quickstart :link: quickstart :link-type: doc Install and render your first RST snippet in 5 minutes. ::: :::{grid-item-card} Topics :link: topics/index :link-type: doc Template tags, template filters, class-based views, and FAQ. ::: :::{grid-item-card} API Reference :link: api/index :link-type: doc Every public class, function, and exception. ::: :::{grid-item-card} Contributing :link: project/index :link-type: doc Development setup, code style, release process. ::: :::: ## Install ```console $ pip install django-docutils ``` ```console $ uv add django-docutils ``` See [Quickstart](quickstart.md) for configuration and first steps. ## At a glance ```django {% load django_docutils %} {% rst %} Title ===== *reStructuredText* rendered to HTML inside a Django template. {% endrst %} ``` ```{toctree} :hidden: quickstart topics/index api/index project/index history GitHub ``` --- # Code Style Source: https://django-docutils.git-pull.com/project/code-style/ # Code Style ## Formatting django-docutils uses [ruff](https://github.com/astral-sh/ruff) for both linting and formatting. ```console $ uv run ruff format . ``` ```console $ uv run ruff check . --fix --show-fixes ``` ## Type Checking Strict [mypy](https://mypy-lang.org/) with [django-stubs](https://github.com/typeddjango/django-stubs) is enforced across `src/` and `tests/`. ```console $ uv run mypy ``` ## Docstrings Follow [NumPy-style docstrings](https://numpydoc.readthedocs.io/en/latest/format.html) for all public functions and methods. ## Imports - Always include `from __future__ import annotations` at the top of Python files. - Use `import typing as t` and access via namespace: `t.Optional`, `t.Dict`, etc. --- # Development Source: https://django-docutils.git-pull.com/project/contributing/ # Development Install [git](https://git-scm.com/) and [uv](https://github.com/astral-sh/uv). Clone: ```console $ git clone https://github.com/tony/django-docutils.git ``` ```console $ cd django-docutils ``` Install packages: ```console $ uv sync --all-extras --dev ``` ## Running Tests ```console $ uv run pytest ``` Run a single test file: ```console $ uv run pytest tests/test_template.py ``` Watch tests: ```console $ uv run ptw . ``` ## Building Docs ```console $ uv run sphinx-build docs docs/_build ``` Live-reload: ```console $ uv run sphinx-autobuild docs docs/_build ``` --- # Project Source: https://django-docutils.git-pull.com/project/ (project)= # Project Information for contributors and maintainers. ::::{grid} 1 1 2 2 :gutter: 2 2 3 3 :::{grid-item-card} Contributing :link: contributing :link-type: doc Development setup, running tests, submitting PRs. ::: :::{grid-item-card} Code Style :link: code-style :link-type: doc Ruff, mypy, NumPy docstrings, import conventions. ::: :::{grid-item-card} Releasing :link: releasing :link-type: doc Release checklist and version policy. ::: :::: ```{toctree} :hidden: contributing code-style releasing ``` --- # Releasing Source: https://django-docutils.git-pull.com/project/releasing/ # Releasing ## Version Policy django-docutils is pre-1.0. Minor version bumps may include breaking changes. Users should pin to `>=0.x,<0.y`. ## Release Process Releases are triggered by git tags and published to PyPI via trusted publishing. 1. Update `CHANGES` with the release notes 2. Bump version in `src/django_docutils/__about__.py` 3. Commit: ```console $ git commit -m "django-docutils " ``` 4. Tag: ```console $ git tag v ``` 5. Push: ```console $ git push && git push --tags ``` --- # Quickstart Source: https://django-docutils.git-pull.com/quickstart/ (quickstart)= # Quickstart ## Installation For latest official version: ```console $ pip install django-docutils ``` Upgrading: ```console $ pip install --upgrade django-docutils ``` (developmental-releases)= ### Developmental releases New versions of django-docutils are published to PyPI as alpha, beta, or release candidates. In their versions you will see notification like `a1`, `b1`, and `rc1`, respectively. `1.10.0b4` would mean the 4th beta release of `1.10.0` before general availability. - [pip]\: ```console $ pip install --upgrade --pre django-docutils ``` - [pipx]\: ```console $ pipx install --suffix=@next 'django-docutils' --pip-args '\--pre' --force // Usage: django-docutils@next ``` - [uv]\: ```console $ uv add django-docutils --prerelease allow ``` - [uvx]\: ```console $ uvx --from 'django-docutils' --prerelease allow django-docutils ``` via trunk (can break easily): - [pip]\: ```console $ pip install -e git+https://github.com/tony/django-docutils.git#egg=django-docutils ``` - [pipx]\: ```console $ pipx install --suffix=@master 'django-docutils @ git+https://github.com/tony/django-docutils.git@master' --force ``` - [uv]\: ```console $ uv tool install django-docutils --from git+https://github.com/tony/django-docutils.git ``` [pip]: https://pip.pypa.io/en/stable/ [pipx]: https://pypa.github.io/pipx/docs/ [uv]: https://docs.astral.sh/uv/ [uvx]: https://docs.astral.sh/uv/guides/tools/ ## Add the django app Next, add `django_docutils` to your `INSTALLED_APPS` in your settings file: ```python INSTALLED_APPS = [ # ... your default apps, 'django_docutils' ] ``` ## Next steps Integate docutils to your django site: 1. {ref}`template_tag` 2. {ref}`template_filter` 3. {ref}`class_based_view` ::: --- # Class-based view Source: https://django-docutils.git-pull.com/topics/class_based_view/ (class_based_view)= # Class-based view ## Setup :::{seealso} {ref}`Quickstart ` ::: 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, } ] ``` ## Introduction to views 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' ``` *yourapp/templates/home.rst*: ````restructuredtext hey --- hi ## A. hows B. it C. going D. today **hi** *hi* ```` *yourapp/templates/base.html*: ```django {{content}} ``` Output: ```html

hey

hi

  1. hows
  2. it
  3. going
  4. today

hi hi

``` :::{admonition} Explore the API - {class}`~django_docutils.views.DocutilsView`, {class}`~django_docutils.views.DocutilsResponse` - {class}`~django_docutils.lib.views.RSTMixin`, {class}`~django_docutils.lib.views.RSTRawView`, {class}`~django_docutils.lib.views.RSTView` - {class}`~django_docutils.template.DocutilsTemplates`, {class}`~django_docutils.template.DocutilsTemplate` ::: --- # FAQ Source: https://django-docutils.git-pull.com/topics/faq/ (faq)= # FAQ ## General ### What is reST, RST, reStructuredText? [reStructuredText] is a markup syntax, similar to markdown. ### What is docutils? [docutils] is a python package for parsing and publishing markup. The default docutils package supports reStructuredText. It can also be extended to parse markdown (e.g. [myst-parser]). [myst-parser]: https://github.com/executablebooks/MyST-Parser ## Django Docutils ### Do I need this package to parse reStructuredText in Django? No! [docutils] can always be used directly. This package simply offers template extensions to use docutils in django views. ### What does this package provide? 3 ways to render reStructuredText via docutils in [Django]: 1. {ref}`template_tag` 2. {ref}`template_filter` 3. {ref}`class_based_view` ### Can I copy code from this project to my own? Yes! Go ahead, the project's source is released under the [MIT license] - you are welcome to view the codebase and copy just what you need. [MIT license]: https://github.com/tony/django-docutils/blob/master/LICENSE [docutils]: https://docutils.sourceforge.io/ [reStructuredText]: https://docutils.sourceforge.io/rst.html [Django]: https://docs.djangoproject.com/ --- # Topics Source: https://django-docutils.git-pull.com/topics/ (topics)= # Topics High-level guides covering django-docutils features, configuration, and common patterns. ::::{grid} 1 1 2 2 :gutter: 2 2 3 3 :::{grid-item-card} Template Tag :link: template_tag :link-type: doc Render reStructuredText inside Django templates with `{% rst %}`. ::: :::{grid-item-card} Template Filter :link: template_filter :link-type: doc Use the `rst` filter to convert RST strings to HTML inline. ::: :::{grid-item-card} Class-based View :link: class_based_view :link-type: doc Serve RST-backed pages with `DocutilsView`. ::: :::{grid-item-card} FAQ :link: faq :link-type: doc Common questions about reStructuredText and django-docutils. ::: :::: ```{toctree} :hidden: template_tag template_filter class_based_view faq ``` --- # Template filter Source: https://django-docutils.git-pull.com/topics/template_filter/ (template_filter)= # Template filter ## Setup :::{seealso} {ref}`Quickstart ` ::: Make sure `django_docutils` is added your `INSTALLED_APPS` in your settings file: ```python INSTALLED_APPS = [ # ... your default apps, 'django_docutils' ] ``` ## Using the django filter In your HTML template: ```django {% load django_docutils %} {% filter rst %} # hey # how's it going A. hows B. it C. going D. today **hi** *hi* {% endfilter %} ``` Output: ```html

hey

hi

  1. hows

  2. it

  3. going

  4. today

hi hi

``` :::{admonition} Explore the API - {func}`~django_docutils.templatetags.django_docutils.rst_filter` ::: --- # Template tag Source: https://django-docutils.git-pull.com/topics/template_tag/ (template_tag)= # Template tag ## Setup :::{seealso} {ref}`Quickstart ` ::: Make sure `django_docutils` is added your `INSTALLED_APPS` in your settings file: ```python INSTALLED_APPS = [ # ... your default apps, 'django_docutils' ] ``` ## Using the django tag In your HTML template: ```django {% load django_docutils %} {% rst %} # hey # how's it going A. hows B. it C. going D. today **hi** *hi* {% endrst %} ``` Output: ```html

hey

hi

  1. hows

  2. it

  3. going

  4. today

hi hi

``` :::{admonition} Explore the API - {func}`~django_docutils.templatetags.django_docutils.rst` ::: ---