API2XML is a documentation tool orthoganal to Java's javadoc tool. Thas is, API2XML extracts embedded sourcecode documentation and generates XML source, which can then be easily translated into HTML.
You can see an example of the end results at the REXML API Documentation page.
0.5.8: Better handling of events encountered outside of a class. Recursing into subdirectories never worked. Now it does.
0.5.7: Added class inheritance graphing. You can now abbreviate keywords; @param can be shortened to @p, @return to @r.
0.5.5: Includes weren't being written.
0.5.4: Have added hacks to avoid problematic situations. I'm starting to think that I'm going to have to implement a full Ruby interpreter just to parse source files :-/. In any case, Strings are the current problem; if you have a multi-line string, and the second line has the word "end" in it, you will confuse api2xml, and you'll start finding parts of the documantation for the API in random places.
Ruby already has RD, but I don't like RD. First, RD is dumb. I'm not saying that RD is a bad idea; I mean to say that RD itself doesn't help the documentor much -- RD documentation is just source comments with no contextual information drawn from the sourcecode. Second, RD uses the =begin...=end source documentation markup, which I find tedious; =begin and =end must start at the beginning of the line, and this disturbs my indentation; I just don't like it, aesthetically.
John Johnson has a priori written a utility called RubyDoc (curse his eyes!); you can find it at the RubyDoc homepage. Want to hear a funny story? I knew I had seen John's software, but when I went looking for it, I couldn't find it anywhere. So I wrote my own over the weekend. Then, come Monday, I went into my office and there on the computer was a copy of RubyDoc. That's a funny story! It is always funny when someone wastes four hours (or more!) of time on something that someone else has already written, like the Gnome people did with KDE. In any case, I found that RubyDoc wasn't exactly what I was looking for, so I continued to refine API2XML. I won't say which is better, but I like the fact that API2XML generates XML which can be styled. I don't like the fact that with API2XML you have to have an external XSLT processor, and there isn't a non-alpha one available for Ruby (at the moment).
API2XML uses the Ruby hash comments, and it interprets sourcecode to provide context for the comments, similar to javadoc. This relieves the programmer of some of the tedium of writing API documentation, which in turn makes it more likely that the programmer will actually write documentation.
I wrote this specifically for my REXML project, because I needed a way of nicely documenting the API for general consumption. If you use this, let me know, because I probably will only devote enough time to it to get it to meet my needs, otherwise.
There isn't much to install. You have to have REXML installed, or at least have the rexml directory in your Ruby include path, but other than that, just run the api2xml.rb application.
As of version 0.5.2, you no longer have to place the style sheets in the current directory when running transform.rb... IF you run it directly as a script, and not as an argument to the ruby command (IE, you run it with "translate.rb", not "ruby translate.rb"). For this to work, the stylesheets have to be in the same directory as the translate.rb executable. If you want to provide your own stylesheets, you can put them in the directory you call translate.rb from; they will override the default stylesheets. These stylesheets must be called, strangely enough, class.xsl and module.xsl.
If you really want some fancy API documentation, make sure you grab Robert Feldt's GraphR package2. If you do, you'll get a nice graphic class hierarchy diagram. API2XML will autodetect whether or not GraphR is installed (at runtime, not install time). If so, it will generate the inheritance graph, and link to it from the index.html file. At the moment, it generates Postscript, SVG, and PNG versions of the graph; only the Postscript is linked to3. If you want to see an example of this graph, here is the REXML graph.
API2XML recognizes comments on a number of objects. These objects are:
In each of these cases, simply provide hash comments immediately preceeding the item to be documented. Blank lines may occur between the comments and the item, but no other code may. Comments may also occur at the end of a line, in which they will be included with any previous comments; comments after will not be included.
In the comments for method definitions, you can supply keywords. At the moment, the only keywords are @param and @return; they function like their JavaDoc equivalents.
# Use this method to send a cow to Uzbekistan. # @param weight the weight of the cow to send, in pounds. # @return delivery confirmation, of class CowPie def send_cow_now( weight=1200 ) # ... end
Once you've commented your code, run api2xml.rb and supply, as a command-line argument, the name of the directory that contains the sources. The script will make a directory called "api", and in that will mirror the directory structure of the directory you supplied on the command line.
api2xml.rb rexml
In this case, my sources are in the directory "rexml". A directory called "api/rexml" will be created, with an XML document for every class and module in the ruby sources found in "rexml". Note that your sources must have the extension of ".rb" or ".ruby"; all other files are ignored.
Once done, you may transform the XML documents to HTML. If you have xalan installed, and a "xalan" executable in your path, you can use the transform.rb script to do this conversion for you.
transform.rb
If you have another XSLT processor you want to use, edit the transform.rb script and change the processing command; it should be pretty easy to figure out.
Currently, you have to find your own entry point; there is no global index generated. Soon, young Jedi.
The most common problem will be when you try to execute either api2xml.rb or transform.rb, and your shell tells you it can't find the command. The ruby executable normally lives in one of two places: /usr/local/bin or /usr/bin. If you compiled it yourself, it will probably be in /usr/local/bin. If you installed it with a RPM, it will probably be in /usr/bin. Change the first line of each script to point to the proper location of the ruby executable on your machine.