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

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].

E.g.:

.. 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
    ==================================================

: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.

Example:

: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.

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

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

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

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 ws_sh2rst.py, converts a shell script into a ReST document. (See check-ws_sh2rst.sh - test for ws_sh2rst.py).

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.

tools/ws_rst2latex.py
tools/ws_rst2man.py
tools/ws_rst2man.py
tools/ws_rst2odt.py
tools/ws_rst2latex.py
tools/ws_rst2pdf
tools/ws_rst2html.py
tools/ws_rst2pseudoxml.py
tools/ws_sh2rst.py

: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 https://bitbucket.org/wolfmanx/ws_docutils

: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.

:rem:`|||:sec:|||`Copyright

Copyright (C) 2012, Wolfgang Scherer, <sw@wiedenmann-seile.de>. Sponsored by Wiedenmann-Seile GmbH.

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