Category "IDLdoc"


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.

[GitHub repo]: http://github.com/mgalloy/idldoc
[releases]: https://github.com/mgalloy/idldoc/wiki/Releases "Releases"

[^1]: You can always get the latest version from the [GitHub repo].

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.

[GitHub repo]: http://github.com/mgalloy/idldoc
[download]: http://michaelgalloy.com/wp-content/uploads/2014/05/idldoc-3.6.0-beta.zip "IDLdoc 3.6.0 beta .zip"

[^1]: You can always get the latest version from the [GitHub repo].

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.

[IDLdoc repo]: https://github.com/mgalloy/idldoc "mgalloy/idldoc"
[CONGRID]: http://exelisvis.com/docs/CONGRID.html "CONGRID (IDL Reference)"

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

Third party libraries are also included in the "[Documentation Center][Doc 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.

[^1]: Although I have never really released a full version of my library. I'm trying to get a more complete version together—expect news on this soon.

[IDL Help]: http://idldatapoint.com/2012/10/08/idl-help-on-the-web/ "IDL Help on the web"
[Doc center]: http://www.exelisvis.com/docs/ "Docs - Documentation Center"
[CONGRID]: http://www.exelisvis.com/docs/CONGRID.html "Docs - CONGRID"

IDLdoc wasn't displaying the Categories on the Categories page. Download at the [IDLdoc project site][IDLdoc].

[IDLdoc]: http://idldoc.idldev.com "IDLdoc Trac 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][idldoc-downloads].

[idldoc-downloads]: http://idldoc.idldev.com/wiki/Downloads "IDLdoc downloads"

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][prompt-example].

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][3.5-beta] ([source code link][3.5-beta-src]).

[3.5-beta]: http://michaelgalloy.com/wp-content/uploads/2012/09/idldoc-3.5.0beta.zip "IDLdoc 3.5 beta"
[3.5-beta-src]: http://michaelgalloy.com/wp-content/uploads/2012/09/idldoc-3.5.0beta-src.zip "IDLdoc 3.5 beta (src)"
[prompt-example]: http://docs.idldev.com/idllib/analysis/mg_n_smallest.html "Example of prompt hiding"

[experiment]: http://michaelgalloy.com/wp-content/uploads/2012/05/prompt_hiding.html "Prompt hiding example"
[sphinx]: http://sphinx.pocoo.org/ "Sphinx documentation"

[^1]: Sphinx is somewhat the Python equivalent to IDLdoc, but much more general.

While looking up some Python docs generated by the excellent [Sphinx][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.

[example-main]: http://idldatapoint.com/2012/05/03/the-merits-of-an-example-main-program "IDL Data Point: The merits of an example main program"
[doctest]: http://docs.python.org/library/doctest.html "Python doctest module"

The IDL Data Point recently had an [article][example-main] 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.

Continue reading "Doc testing thoughts."

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

[IDLdoc downloads]: http://idldoc.idldev.com/wiki/Downloads "IDLdoc downloads"

older posts »