"post"
Wed, 17 Feb 2010 19:04:03 EST
Generating Documentation for cl-mongo
I want to be able to keep the documentation of cl-mongo current when I am adding new features to the package.
The original documentation was generated 'by hand'. I went through the code and made sure I documented the exported classes, methods and functions. This is not really satisfactory. Ideally you want the documentation and the code tightly integrated. Javadoc style documentation, which can be generated from source code annotations would be ideal.
There are various lisp packages available which will pull out the source code comments for the public interface defined in the packages file.
One such package is Edi Weitz's documentation template. This package generates an HTML file with the API description based on embedded comments, which is exactly what I was looking for.
The package does have its quirks/features. It doesn't seem to like embedded HTML or markdown formatting in the lisp code comments, so the API descriptions appear somewhat 'flat'.
In addition I can't define an order on the way the API components are presented and consequently things jump around a-bit.
It also hard-codes licensing information and URLs which are not appropriate for me. The way I dealt with this was to take the generated HTML file and to search and replace the licensing information and URLs.
The next challenge was to integrate the HTML file generated by documentation-template with the README.md. This I accomplished by stripping out the HTML header and appending the resulting HTML file to a markdown formatted file.
The result doesn't look bad and more importantly gives me a way to easily keep my documentation up-to-date.
3475440243