:rem:|||:sec:|||WS Docutils Extensions

Author: Wolfgang Scherer

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

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 :nix:vanishes entirely although it is continued.

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

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

Example:

:field: list
:item: 2

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

field: list 2

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


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 role.py 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 directive.py 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 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