Welcome to rstview’s documentation!

This is a simple Django application around docutils to parse reStructuredText markup.

Features

• Html4 and Html5 writers available;
• Custom reporter to validate source;
• Dedicated view to make a page from a rst source;
• Template tag to directly parse reStructuredText markup;
• Parser driven by configuration so they can be shared without to define them again and again;
• Configuration registry to store multiple different parser configurations;
• Test driven development;

Links

• Read the documentation on Read the docs;
• Download its PyPi package;
• Clone it on its Github repository;

Dependancies

• Django >= 1.7, <1.10;
• docutils >= 0.7;
• Optionnaly (but recommended): Pygments >= 1.2.x to have highlighted syntax in your sourcecode blocks;

User’s Guide

Install

pip install rstview

1. In your settings file add rstview to your installed apps:

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

2. Import default settings:

   from rstview.settings import *
   

3. Finally add these lines in your main urls.py:

   from rstview.discover import autodiscover
   autodiscover()
   

   You may also try to do discovering yourself from your code, see Configuration discovering. For details about registry and configuration see Configuration registry.

Now you can use rstview either from Template tags or Views.

Template tags

rstview.templatetags.rstview_tags.rst_render(source, *args, **kwargs)

Parse and render given string using a parser configuration.

Examples

Basic usage:

{% load rstview_tags %}

{% rst_render SOURCE_STRING %}

Using a specific config set:

{% load rstview_tags %}

{% rst_render SOURCE_STRING config='myconfig' %}

Muting error and warning from parser:

{% load rstview_tags %}

{% rst_render SOURCE_STRING silent=True %}

Everything joined:

{% load rstview_tags %}

{% rst_render SOURCE_STRING config='myconfig' silent=True %}

Tag signature:

{% rst_render SOURCE_STRING [config='default'] [silent=True] %}

Parameters:

source (string) – reStructuredText markup to parse.

Keyword Arguments:  

• config (string) – Name of an option set from settings.RSTVIEW_PARSER_FILTER_SETTINGS.
• silent (bool) – Enable to override default silent mode behavior. Default value is the same as settings.RSTVIEW_PARSER_SILENT.

Returns:

Rendered source from parser.

Return type:

string

Views

class rstview.views.RSTFileView(**kwargs)

Bases: django.views.generic.base.TemplateView

Parse and render a reStructuredText file from given path.

Example

from django.conf.urls import url

from rstview.views import RSTFileView

urlpatterns = [
    url(r'^basic/$', RSTFileView.as_view(
        doc_path="/home/foo/basic/input.rst",
        doc_title="Basic sample"
    ), name='sample-view-basic'),
]

template_name

string – Template file to render. Default to rstview/fileview.html.

doc_title

string – Optionnal document title. Default to None.

doc_path

string – Path to a reStructuredText file, it is recommended you use an absolute path.

This is the only required argument you must allways define.

Default to None.

doc_parser_class

object – A parser class from rstview.parser. Default is rstview.parser.RstExtendedRenderer.

doc_parser_silent

bool – Enable to override default silent mode behavior. Default value is the same as settings.RSTVIEW_PARSER_SILENT.

doc_parser_bodyonly

bool – If True, parser will only return the rendered content, this is the default behavior. Default is False.

doc_parser_configuration

string – A registered configuration name. Default to default.

doc_parser_class

alias of RstExtendedRenderer

get_context_data(**kwargs)

Expand template context with some document related variables:

doc_title

The given document title.

doc_source

Source from given filepath.

doc_html

Rendered source from parser.

doc_parser_configuration

Used configuration name.

Returns:Context variables expanded with variables. Return type:dict

get_document_title()

Get document title from RSTFileView.doc_title

Returns:Document title. Return type:string

get_parser_opts()

Return parser options.

Returns:Options to give to parser.SourceParser:

• setting_key: from class attribute RSTFileView.doc_parser_configuration;
• silent: from class attribute RSTFileView.doc_parser_silent;
• body_only: from class attribute RSTFileView.doc_parser_bodyonly;

Return type:dict

get_source()

Return file source from given path in RSTFileView.doc_path.

Raises:rstview.views.RstViewInvalidException – If RSTFileView.doc_path is not defined. Returns:File content. Return type:string

render_source(source)

Parse given source and return result as safe for django template.

Use RSTFileView.get_parser_opts() to get and give options to parser.

Parameters:source (string) – reStructuredText markup to parse. Returns:Rendered source from parser. Return type:string

template_name = 'rstview/fileview.html'

Default template

exception rstview.views.RstViewInvalidException

Bases: exceptions.Exception

Exception to be raised when RSTFileView usage is incorrect.

References

Settings

RSTVIEW_PARSER_SILENT

Default value for silent mode on parser

Silent means errors and warnings are totally ignored in opposed to un-silent where errors and warnings can be inserted into rendered source and also push to standard output.

Default value is False.

RSTVIEW_PARSER_WRITER

The docutils writer to use, can be html4 (suitable for xhtml too) or html5.

Default value is "html5".

RSTVIEW_PARSER_FILTER_SETTINGS

Default parser configurations used with autodiscovering for initial configuration registry.

Default entry default must allways be present.

Avoid to tamper this setting, instead prefer to use project configuration file or per app configuration files.

Default value:

{
    'default': {
        'initial_header_level': 3,
        'file_insertion_enabled': False,
        'raw_enabled': False,
        'language_code': "en",
        'footnote_references': 'superscript',
        'doctitle_xform': False,
    },
}

These are common parameters that should fit for every basic usage. For details about registry and configuration see Configuration registry.

RSTVIEW_PARSER_ROOT_CONFIGS

Optional project level configurations file, this have to be a correct Python path to a crumb module.

Default value is None.

RSTVIEW_PYGMENTS_CONTAINER_CLASSPREFIX

CSS class prefix for generated Pygments elements when not using inline styles.

Default value is "pygments".

RSTVIEW_PYGMENTS_INLINESTYLES

Enable usage of inline CSS styles in HTML generated by Pygments.

This will fill your HTML with a lot of inline styles. Disabled by default, the recommended way is to style it yourself, because there is not so much to do once.

Default value is False.

RSTVIEW_ERROR_TEMPLATE

Template string used to format error from rst.viewreporter.SourceReporter.

Default value:

"Line {lineno} : {message}"

RSTVIEW_PARSER_SECURITY

Global parser security parameters.

They’re automatically appended to each configurations after every other parameters, so they can override them but never can be overrided.

Default value:

{
    'halt_level': 6,  # Dont halt script execution even if errors
    'enable_exit': 0  # Disable script exit when halt or finished
}

Configuration registry

Registry store configurations by the way of its interface.

Default global registry is available at rstview.registry.rstview_registry and is global for the whole project and apps, you don’t need to fill it again for a same Django instance.

A configuration is a dictionnary of parameters for reStructuredText parser:

{
    'default': {
        'initial_header_level': 1,
        'language_code': "en",
    },
}

Configuration name is used to retrieve parameters from the registry interface.

See Docutils Configuration for a full references of available parser parameters.

class rstview.registry.RstConfigSite(*args, **kwargs)

Rstview configurations registry

Keyword Arguments:  

• initial (dict) – Optional initial dictionnary of configuration. Default
• an empty dict. (to) –

get_names()

Return registred configuration names.

Returns:List of registred names, sorted with default sorted() behavior. Return type:list

get_parameters(name)

Get parameters from given configuration name.

Parameters:name (string) – Configuration name. Returns:Configuration parameters. Return type:string or tuple

get_registry()

Return current registry

Returns:Currrent registry. Return type:dict

has_name(name)

Find if given name is a registred configuration name.

Returns:True if name exists in current registry, else False. Return type:bool

register(name, value)

Register a configuration for given name.

Parameters:

• name (string) – Configuration name.
• value (string or tuple) – Configuration parameters to define.

Raises:

• RstviewConfigAlreadyRegistered if name is allready registered in
• configurations.

reset()

Reset registry to an empty Dict.

unregister(name)

Unregister a configuration from its name.

Parameters:name (string) – Url name. Raises:RstviewConfigNotRegistered if given url name is not registred yet.

update(configs)

Update many configuration.

This works like the Dict.update({..}) method.

Parameters:configs (dict) – A dict of configurations.

rstview.registry.rstview_registry = <rstview.registry.RstConfigSite object>

Default rstview configurations registry for a Django instance.

Configuration discovering

Configurations are registred through files (called configuration file) that are loaded as Python modules where some code can register needed configurations.

Discovering will find these configuration files through project and its enabled applications.

Usually you will want to use automatic discovering with the autodiscover function, so you just have to initiate it once from your project (like in your root urls.py) to load every configuration files.

In some uncommon cases you may need to do discovering yourself from your code, use the discover function to do so.

rstview.discover.autodiscover(filename='rstview_configs')

Automatic discovering for available configurations

Before looking at configurations files, registry start from settings.RSTVIEW_PARSER_FILTER_SETTINGS items if setted, else an empty Dict.

Then it try to load possible root configurations file defined in settings.RSTVIEW_PARSER_ROOT_CONFIGS (as a Python path).

And finally load each configurations files finded in settings.INSTALLED_APPS.

Example

from rstview.discover import autodiscover
autodiscover()

This is something you want to be executed early in your project, usually the urls.py of your project is the best choice.

Keyword Arguments:  filename (string) – Module filename to search for. Default to rstview_configs, so it will search for a rstview_configs.py file at root of every enabled module from settings.INSTALLED_APPS. Returns:List of successfully loaded Python paths. Return type:list

rstview.discover.discover(module_path, filename=None)

Try to discover and load a configuration file from given Python path.

Example

Supposing you made a configuration file at myproject/myapp/rstview_configs.py.

from rstview.discover import discover

discover("myproject.myapp", "rstview_configs")

Parameters:module_path (string) – Python path to scan for filename module. Keyword Arguments:  filename (string) – Optional module filename to search for, default to None. Raises:Exception – Raise any occuring exception from loaded Python path. Returns:Python path (module.filename) for discovered configuration module. If filename does not exists in module, return None. Return type:string or None

Parser

Some helpers around docutils parser to easily parse reStructuredText markup with some options.

Note

This module try to load the pygment directive if available, so you don’t need to load it from your code if you want to use Pygment to highlight code blocks.

class rstview.parser.RstBasicRenderer(*args, **kwargs)

Bases: object

Basic interface around docutils to parse and render reStructuredText markup.

This follows the legacy behaviors of docutils parser, that means:

• Parser errors and warnings are inserted inside the rendered source;
• Errors and warnings are pushed to the standard output;

Example

>>> from rstview.parser import RstBasicRenderer
>>> renderer = RstBasicRenderer()
>>> renderer.parse("Lorem **ipsum** salace")
<p>Lorem <strong>ipsum</strong> salace</p>

get_options(name, initial_header_level=None, silent=False)

Load the given configuration and possibly update parameters with given keyword arguments.

Parameters:

name (string) – Configuration name from registered configurations.

Keyword Arguments:  

• initial_header (int) – To modify option initial_header_level.
• silent (string) – If True, will push the parser reporter level to the lowest verbosiy so errors and warnings are ignored. Default value is the same as settings.RSTVIEW_PARSER_SILENT.

Returns:

Options to give to Docutils parser.

Return type:

dict

get_writer_option()

Get the writer option for parser config depending it’s html4 or html5.

Returns:A dict containing the right writer option name and value. Return type:dict

parse(source, setting_key='default', body_only=True, **kwargs)

Parse reStructuredText source with given options.

Parameters:

• source (string) – reStructuredText source to parse.
• **kwargs – Arbitrary keyword arguments to give as options to RstBasicRenderer.get_options().

Keyword Arguments:  

• setting_key (string) – Configuration name from registered configurations.
• body_only (string) – If True, parser will only return the rendered content else it will return the full dict from Docutils parser. This dict contains many datas about parsing. Default is True.

Returns:

Depending from body_only, it will be a rendered content as a string or a dict containing datas about parsing (rendered content, styles, messages, title, etc..).

Return type:

string or dict

class rstview.parser.RstExtendedRenderer(*args, **kwargs)

Bases: rstview.parser.RstBasicRenderer

Extended interface for next generation usage.

This promotes some extended behaviors:

• Parser can be used to validate markup out of rendered document;
• Nothing is printed out on standard output;

docutils parser is a bit touchy to use programatically, so we need to apply some monkey patchs before and after parsing.

Example

>>> from rstview.parser import RstExtendedRenderer
>>> renderer = RstExtendedRenderer()
>>> renderer.parse("Lorem **ipsum** salace")
<p>Lorem <strong>ipsum</strong> salace</p>
>>> rendered.is_valid()
True
>>> rendered.get_messages()
[]

format_parsing_error(error)

Format error message datas to a message line.

Parameters:error (tuple) – Message error returned by reporter contain four elements: line number, error code and message. Returns:Formatted message. Return type:string

get_messages()

Get a list of formatted messages

Returns:A list of messages.

is_valid()

Only to be used after parsing

Returns:True if no errors, else False Return type:bool

parse(*args, **kwargs)

Proceed to parsing for validation

We apply monkey patchs on two docutils methods, parse source then unmonkey.

Everytime validation is processed, messages are reseted so it should be safe enough to use the RstExtendedRenderer instance for many documents.

Once done you can access raw error messages datas from instance attribute messages or use RstExtendedRenderer.get_messages to have formatted message lines.

Returns:Depending from body_only, it will be a rendered content as a string or a dict containing datas about parsing (rendered content, styles, messages, title, etc..). Return type:string or dict

rstview.parser.build_output(source, output_filepath, **kwargs)

Very basic shortcut helper to build a file from rendered reStructuredText source.

Parameters:

• source (string) – reStructuredText source to parse and render.
• output_filepath (string) – File path where to write rendered source.
• **kwargs – Arbitrary keyword arguments to give as options to rstview.parser.SourceParser.

Html5 writer

Original code is from ‘Bradley Wright’ on Github :

https://github.com/bradleywright/rst-to-semantic-html5

Stealed and modified because i wanted to keep <section/> behavior but not to follow the same way than ‘rst-to-semantic-html5’.

class rstview.html5writer.SemanticHTML5Translator(document)

This is a translator class for the docutils system. It will produce a minimal set of html output. (No extra divs, classes over ids.)

It also aims to produce HTML5 (section etc.)

visit_literal_block(node)

No classes please

class rstview.html5writer.SemanticHTML5Writer

This docutils writer will use the SemanticHTML5Translator class below.

class rstview.html5writer.abbreviation(rawsource='', text='', *children, **attributes)

Node for abbreviations with explanations.

class rstview.html5writer.kbd(rawsource='', text='', *children, **attributes)

Node for kbd element

Developer’s Guide

Development

Development requirement

rstview is developed with:

• Test Development Driven (TDD) using Pytest;
• Respecting flake and pip8 rules using Flake8;
• Sphinx for documentation with enabled Napoleon extension (using only the Google style);
• tox to test again different Python and Django versions;

Every requirement is available in file dev_requirements.txt (except for tox).

Install for development

First ensure you have pip and virtualenv installed, then in your console terminal type this:

mkdir rstview-dev
cd rstview-dev
virtualenv .
source bin/activate
pip install -r https://raw.githubusercontent.com/sveetch/rstview/master/requirements/dev.txt

rstview will be installed in editable mode from the last commit on master branch.

Unittests

Unittests are made to works on Pytest, a shortcut in Makefile is available to start them on your current development install:

make tests

Tox

To ease development again multiple Python and Django versions, a tox configuration has been added. You are strongly encouraged to use it to test your pull requests.

Before using it you will need to install tox, it is recommended to install it at your system level so dependancy is not in tests requirements file:

sudo pip install tox

Then go in the djangocodemirror module directory, where live the setup.py and tox.ini files and execute tox:

tox

Documentation

You should see about sphinx-autobuild for a watcher which automatically rebuild HTML documentation when you change sources.

When installed you can use following command from docs/ directory:

make livehtml

Changelog

Version 0.4.0 - 2016/10/23

• Added a configuration registry and use it instead of directly getting/setting configurations from settings.RSTVIEW_PARSER_FILTER_SETTINGS;
• Now configurations can be added/updated/removed per application through registry interface;
• Now settings.RSTVIEW_PARSER_FILTER_SETTINGS is only used as a startup configuration sets that are not needed to be tampered anymore;
• Added discovering methods to discover configuration files from enabled applications;
• Added tests for registry and discovering;
• Updated documentation to include configuration registry and all;
• Removed some unused settings:
  • RSTVIEW_PARSER_ENABLE_FILE_INSERTION;
  • RSTVIEW_PARSER_ENABLE_RAW_INSERTION;
  • RSTVIEW_PARSER_LANGUAGE_CODE.

Version 0.3.2 - 2016/07/26

• Fixed tests settings and conftest so tests can run correctly through tox;
• Added Django 1.7, Django 1.8, Django 1.9 support since these versions have passed tests through tox;

Version 0.3.1 - 2016/07/26

• First try to use tox for tests;

Version 0.3.0 - 2016/07/24

• Added unittests with Py.test and a dummy project for tests;
• Added better documentation using Sphinx+Autodoc+Napoleon;
• Now require for Django==1.8;
• Major changes in modules and structure:
  • rstview.parser has been refactored to contain everything in two classes;
  • Improved view rstview.views.RSTFileView to be more flexible;
  • Default shipped view template now inherits from skeleton.html instead of base.html;
  • Template filter source_render has been dropped in profit of template tag rst_render which has more options;
  • Dropped old sample rstview/rst_sample.rst;
  • rstview.views.RSTFileView now raise an exception if doc_path attributed is empty;

Version 0.2.1 - 2014/08/17

Minor update for README.

Version 0.2.0 - 2014/08/16

• Added source_render template filter;
• Updated README;