:rem:`|||:sec:|||`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.

:rem:`|||:sec:|||`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.

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

:rem:`|||:sec:|||`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`

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

:rem:`|||:sec:|||`Extended :raw:-like Functionality

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

:rem:`||:sec:||`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 :nhtml:`not` HTML :npdf:`and`:pdf:`but` it is :npdf:`not` PDF.

:rem:`||:sec:||`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 :pdf:`(but obviously not for PDF!)`:

:rem:`||:sec:||`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,

:rem:`||:sec:||`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,

:rem:`|||:sec:|||`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) ;-)).

:rem:`|||:sec:|||`Tool Scripts

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


:rem:`|||:sec:|||`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

:rem:`|||:sec:|||`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.