WS Docutils Extensions

Author: Wolfgang Scherer

Contents

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.

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.

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
item:2

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

The specified part of example.html:


      <table>
        <tbody>
          <tr><td>cell1</td><td>cell2</td><td>cell3</td><td>cell4</td></tr>
          <tr><td>cell1</td><td>cell2</td><td>cell3</td><td>cell4</td></tr>
          <tr><td>cell1</td><td>cell2</td><td>cell3</td><td>cell4</td></tr>
        </tbody>
      </table>
    

is included as-is :

cell1cell2cell3cell4
cell1cell2cell3cell4
cell1cell2cell3cell4

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,
    }

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,
    }

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) ;-)).

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

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

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

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.

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