reStructuredText to HTML

I've recently decided to use reStructuredText for making notes and needed a method to convert them into html. The reStructuredText contains code snippets as well as mathematical notation so the conversion process needed to be able to handle that.

docutils is the obvious candidate to do the conversion, however it doesn't do syntax highlighting or MathML out of the box, so I needed to find extensions that could.

I decided to use Pygments for the syntax highlighting of the code snippets. The Pygments package comes with a file rst-directive.py that creates a directive called 'sourcecode' that can then be used to define code snippets.

For the maths I found rst2mathml which adds a directive converting tex math notation in a reStructuredText file to MathML in the html.

So the list of steps to get this working was:

• Install some stuff needed for rst.

  sudo apt-get install python-docutils

• Download rst2mathml.py.

• Found rst-directive.py in the Pygments constellation and made a copy renamed to rst_directive.py in the same directory as rst2mathml.py.

• Add the following line to the top of rst2mathml.py so that the sourcecode directive can be used.

  import rst_directive

• Create a stylesheet for syntax highlighting.

  pygmentize -S default -f html -a .highlight > style.css

• Create script to do conversion.

convert.sh

#!/usr/bin/env bash

echo input file name is $1
stem=${1%.rst}
python /home/ben/Documents/Notes/rst2mathml.py --stylesheet-path=/home/ben/Documents/Notes/style.css $1 > $stem.xhtml