Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
.mpe extensions for Python Docutils and reStructuredText
Python HTML CSS

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
atlassian,notationhelp.action_bestanden
doc
dotmpe
examples
lib
log/du
test
tools
var
.gitignore
.lvimrc
Issues.rst
Makefile
ReadMe.rst
Rules.mk
Sitefile
atlassian,notationhelp.action.html
docutils.dtd
du-transforms,cache.rst
extractors.rst
man-de.1.man
man-de.1.txt
rst2html.txt
transforms.rst

ReadMe.rst

Docutils extensions

Author: Berend (dotmpe)

My collection of extensions for Python docutils.

This document attempts to present an overview of the project tree. First a description is given of the command-line utilities in tools/, second a list summary is given of the source code, whose main files will be documented themselves. Lastly a global log and list of further references follows.

Utilities

tools/build.py

Can be symlinked to any publisher wanted, ie. rst2latex, etc.

This should be the main entry point, but dupub.py (docutils publisher with extensions) may be (more) functional..

Development

Completed

  • Left- and right-margin decoration.
  • Various document transforms and additional document settings (with command-line options). See Transforms (dotmpe.du.ext.transform).
  • These transforms are used by dotmpe.du.ext.reader.mpe.Reader.
  • Several Nabu Extractor, Storage pairs, see Extractors (dotmpe.du.ext.extractor) but nothing complex yet.
  • rST forms framework. Use rST documents as forms, but gotten a bit out of use and no unittests. The implementation includes retrieving data from a document according to the form specification, which includes type conversion and value validation.
  • Monkey patched docutils.{readers,parser,writers}.get_*_class() to load components from my lib. Enable 'extension' by importing dotmpe.du.ext.

In progress

  • dotmpe.du.builder has some packages with specific Reader/Parser/Writer component configurations, but frontend is undergoing work.
  • Front-end development in Blue Lines. Simplified frontend for NodeJS.
  • rST rewriter.

ToDo

  • re-evaluate include, literal and raw dereferencing. want something like subdocs but low on the list of wannahaves.
  • expose extractor and storage parameters on command line as other components.
  • create a storage context that can provide Nabu stores. see extractors.rst_
  • --use-bibtex=USE_BIBTEX from latex2e may be nice practical example of external resource framework/metadata integration.
  • directive options are not all i18n'd
  • Du/rST examples
    • example: form demonstration
    • example: example rSt on inline references and roles
    • example: breakcrumbs
  • rST directives for breadcrumbs, testing etc? options?
  • Issues

Devel

  • Docs
  • Validation. Relax-NG?
  • I'd like an alternative (even less vertically hungry) markup for titles. What about === title or = title = block formats. Nice and short where appropiate.
  • Same point goes for tables (title would be header, left or right aligned etc.) If rstwriter restructured is finished I might have stab at this.
  • propose breadcrumb and other generate transforms on devel list, Lea mentioned breadcrumbs (long ago..).
  • Is the XML tree the complete representation whereof the rST is a variant, a perhaps lossy representation? I think it loses some things, should keep track during rstwriter devel.

Branches

GIT
master
all development happened here until dev was branched.
dev

Sort of the master now. Testing only functional stuff, may be deceptive as not everything is unit/systemtested?

tests: 8 OK
dev_rstwriterobjects

separate development branch for rstwriter restructuring, trying to OO-ify and add some elegance.

test: 57; 25 failures, 2 errors
dev_simplemuxdem

trying a lossless read/write using the rST SM base with a simple text format, to understand the rSt parser statemachine.

tests: 2 OK

Abandoned while I do get more insight into the rSt parser machinery.

dev_form
Splitting topic of dev for separate testing. Possibly a few hacks while core/frontend is in flux.
dev_rstwriter

While things left to be desired before finishing dev_rstwriterobjects, implement and test reStructuredText writer.

tests: 66, 9 failed

rST writer

Although still heavily a work in progress, I think it may be almost ready for simple rST-to-rST processes... should push through. Tables may be low on the wishlist though, get everything else first. Then figure out nested parser for tables. Perhaps need to think about nested writer for current literal blocks already?

Getting Started

  • May need latest docutils from SVN, sorry not sure about current version but Du has not been in a lot of flux so..
  • For some automated tasks on this project package use make [help|..].
  • There is no setup script yet.
  • Skim the docs.

Testing

The main development is at the rST writer. The module is used as a crude script during bugfixing:

python dotmpe/du/ext/writer/rst.py [\*.rst]

This prints the documents in source and psuedoxml, conveniently side-by-side.

Currently only lossy rST writing is tested by 'make test' because that generates enough work and bugreports for now.

rST writer testcases are generated for all files matching var/test-*.rst.

Dependencies

pip install coverage
  • some symlinks in lib/
  • my mkdocs project to build from Rules.mk
  • xmllint

Log

2009 September
  • Starting my own project for use with Blue Lines, custom 'margin' directives and HTML writer components.
2010-11-04
Stefan Merten published his xml2rST and included an installer. He also has rST2gxl 'producing GXL which can be transformed to dot' and rST2diff 'comparing two input files producing a marked up difference output'.
2010-12-01
  • Integrating figure label patch by Alex @ du mailinglist.
  • Created subclass of latex2e writter for this.
2011-01-12
2011-04-16
  • Updated testing so dynamic test cases (generated from file) are handled as usual by unittest.main, no more need to aggregate testsuites. Lossless testing is disabled for now.
2013 November
  • Retaking to development.

  • Adding new tests. First unnittests for builder. Need frontent/CLI system tests.

  • Splitting testing and non-functional stuff to sep. branches.

  • Adding build log and validation for test markup files. There should not be any log files in var/ otherwise some test-file does not completely check out (rm var/test-rst*.log && make test-validate-files).

    Should clean/check out examples/ too.

2014 August
  • Taking up Builder.process again for ~/htdocs. Started working on setup-file too, and considering Sitefile concept.
Something went wrong with that request. Please try again.