A Gem for┬áChristmas

The holiday has offered me enough time to rename, renamespace, lightly document, and package up MathViz as a gem.

I renamed MatLat, a somewhat awkward name, to MathViz, which does a slightly better job of saying what it does. Later, I Also lifted all the global modules and classes into the MathViz namespace to cut down on pollution.

I moved the examples into a dedicated directory, and then added E = mc2 as a more gentle example. I cut down an a common tripping point by taking the output name out of the program text and giving it a default based on the main filename.

RDoc

Building up the RubyGem machinery involved setting up the documentation. The first piece of documentation was the README file; I’m not sure that there is a happy medium between BitBucket, GitHub, and RDoc for what this file should be named, though I haven’t made a concerted attempt to find one. In any case I ran into the same difficulty I had with Bondage – I want the sample code in the documentation to be an executable file I can test. Bondage solved it by gluing together bits of files. MathViz is trying an erb template to handle the include.

Another stumbling block for RubyGems and RDoc is images. I wanted to include a output image, but there appears to be no way include a binary file in the automatically generated documentation trees. Even if I could add something to the project, I’m not sure how much good it would do: I found the RDoc on my system was ancient until I updated the gem. I have a rake task that copies the file after generation, but this mechanism isn’t used by the gem installer.

I also ran into some difficulty with the code documentation. I like the DarkFish templates better than the frames version, and the newer version has better handling of metaprogrammed methods. The new syntax requires a comment per method, which somewhat spoils the conciseness, and in MathViz’s case there really isn’t much to say about a standard operator.

I did discover rdoc.info, which though sorely lacking an about page, aims to be a central ruby documentation source. I generated documentation for MathViz and Bondage.

Posted Friday, December 25th, 2009 under Devlog.

Comments are closed.