WS Docutils Extensions

Author: Wolfgang Scherer



This package provides a span role and a div directive, fixes the raw role for Docutils and provides a raw_role extension for rst2pdf.

The span role and the div directive are generalized from the raw role and raw/include directives.

There is also a fully transparent comment role for inline comments that do not leave a trace:

.. role:: nix(comment)

This :nix:`vanishes entirely although it` is continued.

This is continued.

In-Line Comments

Among other things, the span role allows to define an interpreted text role for a non-existing format which effectively provides inline comments[1].


.. role:: rem(span)
   :format: ''

:rem:`|||:sec:|||`\ Purpose

The div directive basically works the same way[2].

This ReST source, does not cause any output, if ws_docutils is active:

.. div::
   :format: ''

   Elaborate Block comment ...


    Quoted block trick to include Section Headers
[1]Actually a :remove: role is sufficient for this task and may one day be part of Docutils. But this project was really an experiment how far one could go with Docutils. And I must say, I am really impressed.
[2]It is not possible to place section headers under a div. That would require extensive changes to the Docutils parser. And that is, when I gave up.

Distance between Footnotes/Field Lists and Section Headers

The HTML output (at least with my style sheets) lacks a distance, when a section ends with a table element. Placing a span role comment on a line by itself will generate an empty paragraph in the HTML output, which solves the problem without changing the CSS.


:field: list
:item: 2

:rem:`produce a distance between footnote and next section header in output`

Extended :raw:-like Functionality

The span role and the div directive work like an extended raw role and raw/include directives.

span role: NOT FOR

It is possible to specify several formats instead of just one and it is also possible to negate a format with e.g., !html to produce output for all formats except HTML.

This input:

This output is :nhtml:`not` HTML :npdf:`and`\ :pdf:`but` it is :npdf:`not` PDF.

Produces different output for HTML and PDF:

This output is HTML and it is not PDF.

div directive: Partial includes

Example div for HTML:

.. div:: html
   :file: example.html
   :start-after: \|:here:| -->
   :end-before: <!-- \|:here:|

The specified part of example.html:


is included as-is :


All span Role Options

I'm sorry not having enough time, so you have to consult the source code in to find out what they do.

span_role.options = {
    'format': directives.unchanged,
    'literal': directives.flag,
    'raw': directives.flag,
    'pfx': directives.unchanged_required,
    'sfx': directives.unchanged_required,
    'ref': directives.flag,

All div Directive Options

I'm sorry not having enough time, so you have to consult the source code in to find out what they do.

option_spec = {
    'format': directives.unchanged,
    'literal': directives.flag,
    'raw': directives.flag,
    'start-line': directives.nonnegative_int,
    'end-line': directives.nonnegative_int,
    'start-after': directives.unchanged_required,
    'end-before': directives.unchanged_required,
    'file': directives.path,
    'url': directives.uri,
    'tab-width': directives.nonnegative_int,
    'encoding': directives.encoding,
    'inline': directives.flag,
    'debug': directives.flag,

Shell Script Documenter

The example python program, converts a shell script into a ReST document. (See - test for

It demonstrates, how tagging can be used to create automated documentation. (It's sort of like a doxygen for sh(1) ;-)).

Tool Scripts

There are some scripts adapted from Docutils and rst2pdf, which include the span/div extension.


Installation/Source Code

The package is available on PyPI:

$ easy_install ws_docutils

The source code is also available as a mercurial repository on bitbucket:

$ hg clone

Historical Note

This module was originally written for Docutils version 0.8 and rst2pdf version 0.16.

Since it still works with Docutils version 0.8.1 and rst2pdf version 0.91, I decided I might as well publish it.

Since at the time I just started out to explore Python, the code is not very well written and I beg forgiveness for it not being actually pythonic.

The orginal reasoning and baby steps that begat this gorilla patch are available in reStructuredText Inline Comments.


Copyright (C) 2012, Wolfgang Scherer, <>. Sponsored by Wiedenmann-Seile GmbH.

The module source code is placed in the public domain following the rest of Docutils.

See section GNU Free Documentation License for license conditions of the documentation, and License for Sphinx for some of the HTML stylesheets.