I cleaned up a few visual bugs in the beta and IDLdoc 3.6 is ready for release. Get the new version at the (releases)^[1] page of the GitHub IDLdoc wiki. Features are the same as listed for the beta:

• Checks for updates when using the VERSION keyword.
• Added Exelis VIS Doc Center output.
• Provides links to IDL library routines referenced in rst markup code syntax.
• HTML rst markup directive to include HTML directly into output (contributed by Phillip Bitzer).
• Reporting only non-empty, non-comment lines in routines/files now.
• Improved algorithm for computing cyclomatic complexity and also reporting modified cyclomatic complexity.
• Updated to MathJax 2.0 and using the complete MathJax distribution for better LaTeX rendering.
• Listing methods inherited from parent classes.
• Miscellaneous bug fixes.

UPDATE 6/11/14: I released 3.6.1 adding some missing library routines in the .sav file. Download is on the same page.

I haven’t released IDLdoc for awhile and quite a few new features have accumulated^[1] (download):

• Checks for updates when using the VERSION keyword.
• Added Exelis VIS Doc Center output.
• Reporting only non-empty, non-comment lines in routines/files now.
• Improved algorithm for computing cyclomatic complexity and also reporting modified cyclomatic complexity.
• Updated to MathJax 2.0 and using the complete MathJax distribution for better LaTeX rendering.
• Listing methods inherited from parent classes.
• Miscellaneous bug fixes.
• Provides links to IDL library routines referenced in rst markup code syntax.
• HTML rst markup directive to include HTML directly into output (contributed by Phillip Bitzer).

If you check it out, please let me know if you have any issues. Formal release should happen in the next week or two.

When using the rst markup, IDLdoc has been able to lookup the names of routines, files, directories, keywords, etc. when referencing them using syntax like:

; :Returns:
;   Returns a string array for the names if `NAMES` keyword is set.

Here a link to the “NAMES” keyword is created automatically by IDLdoc. IDLdoc searches the namespace “around” the mention to determine what is given priority, i.e., look first for keywords and parameters of the given routine/method, then check for routines/methods in the current file, classes in the current file, the name of the current file, etc. expanding to include all the symbols defined in the hierarchy of files being documented.

New in the development version of IDLdoc is another check against the names of the IDL library routines, producing a link to the online help on exelisvis.com/docs. For example, the following comments would automatically link to CONGRID:

; Resize an image similarly to `CONGRID`. Advantage over `CONGRID` is
; that nearest neighbor interpolation is used even for multiple band
; images.

To get the development version of IDLdoc at any time, check the IDLdoc repo on GitHub.

The IDL Online Help is now online! I can now finally link to the help page for CONGRID.

Third party libraries are also included in the “Documentation Center”. My personal library^[1] is present, but the parsing of my routines used by the Doc Center doesn’t catch all the comments in the headers. I’m working on a release of IDLdoc that will produce Doc Center compatible output for the third party libraries that use IDLdoc.

IDLdoc wasn’t displaying the Categories on the Categories page. Download at the IDLdoc project site.

IDLdoc 3.5 is out! There are plenty of bug fixes plus the new prompt hiding in code examples in this release. See the full release notes and download it from the IDLdoc project site.

I’m getting ready to release IDLdoc 3.5. This is mostly bug fixes and cleanup, but there is one nice new feature – prompt hiding. This allows the docs to show IDL prompts with commands and expected output in code snippets, but allows the user to hide the prompts and output by clicking “hide prompts”. This is great for copy-and-pasting an example to the command line (while still being able to check your output against the expected output)! For example, see the “Examples” section of the mg_n_smallest docs.

The complete list of fixes and features is:

• Added list of inherited properties to class descriptions.
• Provides workaround for possible bug in IDL where list object contains strange variables that report as the type code for object, but are not actually objects (they are pointers).
• Fixed bug where Categories page showed private or hidden items.
• Added hide/show prompts in code snippets in HTML output from rst markup comments.
• Allow markup in Uses tag when using the rst markup parser. Note: the Uses tag is for a list of files or routines optionally separated by commas, plain text will have commas inserted between words.
• Fixed errors in LaTeX output.

Download (source code link).

While looking up some Python docs generated by the excellent Sphinx documentation tool^[1], I noticed that Sphinx can show/hide the prompts and output in a code snippet. This allows the user to see the full code and output, but then can hit a button and get text suitable for cut-and-pasting onto the command line to try it for themselves. Check out my simple experiment to see how it works.

I will definitely have to work this into an IDLdoc release soon.

The IDL Data Point recently had an article about writing a simple main-level program at the bottom of each file which would give an example or test of the routine(s) in the files. I like this idea and have been doing it for quite a while, but one of the annoyances of this approach is that I also typically want the code to be included in the documentation for the routine, so I end up copy-and-pasting the code into the examples section of the docs (and, of course, reformatting it for the doc syntax). Also, the main-level program just is a place to put some code, I have to do all the work if I actually want to write multiple pass/fail tests.

For example, Python’s doctest module provides a solution to these problems for Python. In your docs, you give a command and its expected output:

>>> [factorial(n) for n in range(6)]
[1, 1, 2, 6, 24, 120]

Then, in the main-level program, you say something like (I’ve omitted some Python details for simplicity here):

doctest.testmod()

When you do the equivalent of running the main-level program, the docs are checked for “>>>” lines which are executed and compared to the output shown in the docs.

It seems like there are several solutions that could be implemented in IDLdoc or mgunit to solve this problem.

1. Create a doctest routine for IDL. This would mean to create a routine like the dockets.testmod() routine in doctest that runs all the lines in the documentation that begin with “IDL>” and compares the results to the output shown below the “IDL>” line.

Advantages: Can be used to easily run tests and compare results to provided output. Test commands and output are included in documentation, but are not present twice in the file.

Disadvantages: None?

2. Conversely, create an IDLdoc include directive, like ..include:: [main-level] that includes the contents of the main-level of the current file. This could be used in the examples section of the docs to include the main-level program.

Advantages: Could also be used to include other files which might be useful in other situations.

Disadvantages: For files with multiple routines in a file, the entire main-level program would be included at the location, even if the main-level program addressed multiple of the routines. Doesn’t help with testing.

3. Allow IDLdoc to do the testing by creating a tests section that would be executed when IDLdoc is run.

Advantages: Can be used to easily run tests and compare results to provided output. Test results appear in the IDLdoc output.

Disadvantages: Need to run IDLdoc to run the tests.

Once nice thing here is that several of these strategies could be implemented. Any ideas, suggestions on what you would like to see? Creating an MG_DOCTEST routine seems like the strongest solution right now, but am I missing something?

IDLdoc 3.4.3 fixes the bug that prevented search results from being displayed.