Overview
Atlassian Sourcetree is a free Git and Mercurial client for Windows.
Atlassian Sourcetree is a free Git and Mercurial client for Mac.
:rem:`|||:sec:|||`WS Docutils Extensions
Author: | Wolfgang Scherer |
---|
Contents
- :rem:`|||:sec:|||`Purpose
- :rem:`|||:sec:|||`In-Line Comments
- :rem:`|||:sec:|||`Distance between Footnotes/Field Lists and Section Headers
- :rem:`|||:sec:|||`Extended :raw:-like Functionality
- :rem:`|||:sec:|||`Shell Script Documenter
- :rem:`|||:sec:|||`Tool Scripts
- :rem:`|||:sec:|||`Installation/Source Code
- :rem:`|||:sec:|||`Historical Note
: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 ==================================================
[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 |
---|---|
item: | 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
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.