rstview 0.2.1

Simple Django application to parse content with ReStructuredText from docutils

Introduction

This is a simple Django application to parse content with ReStructuredText from docutils to HTML5 or HTML4 (suitable for XHTML).

Links

• Download his PyPi package;

• Clone it on his Github repositor;

Requires

• docutils >= 0.7;

Optionnaly (but recommended) you can install Pygments to have highlighted syntax in your sourcecode block :

• Pygments >= 1.2.x;

Installation

Register the app in your project settings like this :

INSTALLED_APPS = (
    ...
    'rstview',
    ...
)

If needed you can change some options, see the “local_settings.py” file to find the available option variables and overwrite them in your project settings file.

Usage

Simpliest usage is to display a ReStructuredText file, like a “README.rst” from a project, assuming the file is a path below your Django project, you can add it to your project “urls.py” file like this :

...
from rstview.views import RSTFileView
...
urlpatterns = patterns('',
    ...
    url(r'^README$', RSTFileView.as_view(doc_file_path="../README.rst", doc_title="Notice"), name='project-readme'),
    ...
)

Default settings is to render document as HTML5, you can change this behaviour to a HTML4 render that is also suitable to use in XHTML documents, see local_settings.RSTVIEW_PARSER_WRITER and override it in settings.RSTVIEW_PARSER_WRITER.

See also local_settings.RSTVIEW_PARSER_FILTER_SETTINGS that contains available parser settings you can use, defined RSTVIEW_PARSER_FILTER_SETTINGS in your project settings to add new parser settings. Default behavior is to use the parser settings named default.

RSTFileView view

This generic view takes three optional arguments :

• doc_file_path : the file path to parse as ReStructuredText file to render;

• doc_title : the title for the document;

• template_name : a custom template file path, by default this is rstview/fileview.html.

Template filter

A template filter is available to simply transform a source text into a ReStructuredText content :

{% load rstview_tags %}

<div class="message">
    {{ message_text|source_render }}
</div>

message_text has to be a variable containing a string, default behavior is to use the default parser settings from settings.RSTVIEW_PARSER_FILTER_SETTINGS.

If you need to use a different parser settings, just give his key name to the filter as the first argument like this :

{% load rstview_tags %}

<div class="message">
    {{ message_text|source_render:"my_parser_settings" }}
</div>

The given parser setting must be defined in settings.RSTVIEW_PARSER_FILTER_SETTINGS to works.