The IDL Developer Network RSS feed came alive this morning after being dormant since early January. The three new items are:

• Multi-threading whitepaper: A useful whitepaper about the thread pool in IDL.
• IDLdoc 3.0 release: This is an old release (we’re on IDLdoc 3.1.1 now), but it’s nice to get some press!
• New tutorials: A few new iTools tutorials.

I have been critical of the ITT VIS website (it has been having some extra problems lately), but this is a step in the right direction.

IDL Workbench 7.0.3 arrived today via the automatic software update mechanism in the Workbench. It provides HDF and netCDF library udpates, better path support, IDLdoc support (rst format only), and even faster code analysis when the Workbench starts. Everything seems to be working well for me during use this afternoon.

Since I’m most excited about the IDLdoc features, I will describe them in a bit more detail after the jump. IDLdoc 3.1 (download) is required to integrate with the Workbench.

One nice IDLdoc feature is the ability to insert IDLdoc headers easily. Right-click in an editor window, “Add Routine Comments” and “Add File Comments” should be choices in the context-menu that pops up. There is a section for IDLdoc in the Preferences to control the formatting and what appears in these inserted headers. The best part of this is that it parses the declaration line for the routine and adds the parameters and keywords it finds. In the example in the image above, I typed the code and the Workbench inserted all the comments as they appear.

Another IDLdoc feature is the ability to mouse over a routine call and see the properly formatted IDLdoc header as a tooltip. For example, mousing over the VIS_RGB2INDEX routine pops up it’s header, as shown below:

One thing that has bothered me before about this is that it uses projects to find the code and not my IDL !path. Because of this, the Workbench often finds multiple copies of my routines because my IDLdoc documentation is in the project (but not in the !path). At least they are all the same since the copies are generated from the original.

I have the framework in place to have IDLdoc produce output besides HTML. This has been a long process beginning in IDLdoc 2.0 when I switched to using templates instead of embedding the HTML code in the IDL code. I have started by writing a set of templates for DocBook output, but intend to write a LaTeX set as well.

Here’s an example PDF of IDLdoc output for a library of routines for visualization I’ve been thinking about.

I just released IDLdoc 3.1 (see full release notes are below). As per this short blog post, IDLdoc is getting integrated into the IDL Workbench. This release adds some rst markup features that the IDL Workbench will use – my favorite is to be able to link to images with:

.. image:: filename

IDLdoc will link to the image and also copy the image file into the output directory (if OUTPUT keyword to IDLDOC routine is used).

1. Added ability to reference images in rst markup. IDLdoc will automatically copy referenced images into the output.
2. In rst markup, illegal characters like < and > are automatically converted to character entities.
3. Added :Description: tag for compatibility with IDL Workbench update.
4. Changed default markup parser to rst when format parser is rst.
5. Miscellaneous small bug fixes.

IDLdoc support will be added to the IDL Workbench in an update planned for June. This will add some really cool features for those who use IDLdoc and the Workbench:

1. enhanced hover help on routines with an IDLdoc header
2. content assistant on tag names when writing IDLdoc comments
3. menu item and keyboard shortcut to insert an IDLdoc routine or file header (and preferences to define what tags you want inserted)

The Workbench will recognize comments in the rst format.

There will be an IDLdoc 3.1 release any day now to add some features necessary to support this and fix a couple bugs.

The svn trunk of IDLdoc has a new feature that I’m excited about: the ability to insert images without having to stick ugly HTML in your code header or copying an image manually into the output. This is part of the rst markup style (so it won’t work unless you set markup_style='rst' in your IDLdoc call or specify it via the “docformat” comment). My goal for the rst markup style is to eliminate any need to put HTML in the code header. I don’t think you should have to make the code header look ugly in order to make the documentation look good.

In the theme river code in the previous article, the header for the routine contains:

; This will produce a result like .. image:: themeriver.png

IDLdoc grabs themeriver.png (relative to the location of the source code file), copies it to the output, and replaces .. image:: themeriver.png with a link to the copy of the image (see output).

If you want to try this, you have to checkout the IDLdoc source code using Subversion:

svn co http://svn.idldev.com/idldoc/trunk

Put the “src” directory of the checkout in your IDL path.

It’s now possible (thanks to some help from engineers at ITT VIS) to get IDLdoc updates via the update mechanism built into the IDL Workbench. This means that you can add a new “Remote update site” that is queried for new updates when you start the Workbench. I think this is a really interesting way to distribute software; I hope I can “subscribe” to other IDL libraries in the future.

For those experienced in getting Eclipse plugins, the URL is

http://updates.idldev.com

For more detailed instructions, see the Workench Updates page on the IDLdoc project site.

One note: if you already have IDLdoc in your !path, you might have to remove it from your path to see the new version.

I added some more documentation to the “Getting Started” page on the IDLdoc project site. Included is a two minute screencast introducing IDLdoc.

By the way, two minutes of screencast took about two hours of production time. I got a lot of valuable experience doing this though, so I’m hoping to do some more of these (for those things that it makes sense for – maybe some IDL Workbench topics).

IDLdoc 3.0 is ready! Highlights of this release:

1. IDLdoc 3.0 was rewritten from scratch to allow it to be released under an open source license. Source code is available from the project website.
2. There are multiple formats for entering comments: the normal IDLdoc style, the traditional IDL comment header, and new style based on restructured text.
3. Ability to do some simple formatting of comments without resorted to putting ugly HTML into your comments.

For more information about this release, see the project website download page.

I’ve given up waiting for ITT VIS to release the source code of IDLdoc 2.0 and rewriting a new version from scratch. I intend to release the source code under a BSD-style license.

I’m using this as an opportunity to make IDLdoc 3.0 much cleaner than the old piecemeal code base of IDLdoc 2.0. I had already been writing many of the underlying libraries used such as array list, hash table, and template classes since I use them for other tasks, so I’ve got a good foundation to build upon.

I’m not sure of how long this will take since I’m doing it in my spare time, but check out a sneak peak of IDLdoc 3.0 output. There will be new features as well in this release: the biggest being several options on the format for comments (i.e. you won’t have to use the “@”-style tags).

If you are interested in keeping up with news about IDLdoc, reporting bugs, asking for features, and general discussion, signup for the mailing list.