Friday, May 1, 2009

Combating reSTlessness

My goal is to come up with as many bad puns as possible to use as post titles during my study of reStructuredText and Sphinx.

Advanced Topics student, Brendan Buso, successfully created several svg illustrations for Sheet 3 in the Gasp Python Course. Unfortunately, he didn't push his changes to the launchpad site, so I'll need to wait until Monday to get them from him. The really cool thing is how easy it was to markup the illustrations in reST, and have them included in the html that it generated. Everything just works! I've waited so many years to arrive at this point, and am once again thankful to the Python community for coming up with an elegant, easy to use solution!

I now need to imerse myself in learning reST. I'm a slow learner, so the approach I will use is to use reST for as many of my documentation needs as possible. Instead of writing in html, I'll write in reST, and then use rst2html to generate the html pages. On an Ubuntu Jaunty system installing rst2html is a simple manner of running:
  • sudo apt-get install python-docutils
This package installs rst2latex, rst2s5, rst2xml, and several others in addition to rst2html. I created a file named hello.rst that contained the following:
Hello World
Then I ran:
  • rst2html hello.rst
which produced this output. rst2html sends its output to standard out, so I actually need to run:
  • rst2html hello.rst > hello.html
to capture it in a file. The html is fairly straight forward, though the CSS is extensive. My next task is going to be wrapping my head around the style generated to see how that can be used to advantage.

No comments:

Post a Comment