To install IDLdoc, simply unzip and place the IDLdoc distribution in your IDL path. Do not separate the contents of the distribution; the code looks for files in locations relative to itself.
A typical call to IDLdoc is:
IDL> idldoc, root='~/projects/mylib', output='~/projects/mylib-docs' This searches for .pro and .sav files in subdirectories of '~/projects/mylib' and places the output in '~/projects/mylib-docs'. The starting page for the output will be '~/projects/mylib-docs/index.html'.
Note: IDLdoc 3.0 copies source code into the output directory, so placing the output directory in your !PATH can cause IDL to choose a (possibly outdated) copy in the docs over the correct source file. It is recommended to either place your docs outside your !PATH or use the NOSOURCE keyword.
There are quite a few keywords to IDLdoc to set various specifications for the output. Further customization can be done through the templates (described in the "Producing customized output" section).
|ROOT||root of directory hierarchy to document; this is the only required keyword|
|OUTPUT||directory to place output; if not present, output will be placed in the ROOT directory|
|TITLE||title of docs|
|SUBTITLE||subtitle for docs|
|EMBED||embed CSS stylesheet instead of linking to it (useful for documentation where individual pages must stand by themselves)|
|OVERVIEW||filename of overview text and directory information|
|FOOTER||filename of file to insert into the bottom of each page of docs|
|NONAVBAR||set to not display the navbar|
|NOSOURCE||set to not put source code into output|
|USER||set to generate user-level docs (private parameters, files are not shown); the default is developer-level docs showing files and parameters|
|STATISTICS||set to generate complexity statistics for routines|
|QUIET||if set, don't print info messages, only print warnings and errors|
|SILENT||if set, don't print any messages|
|FORMAT_STYLE||style to use to parse file and routine comments ("idl", "idldoc", "verbatim", or "rst"); default is "idldoc"|
|MARKUP_STYLE||markup used in comments ("rst" or "verbatim"); default is "verbatim"|
|COMMENT_STYLE||output format for comments ("html", "rst", or "latex"); default is "html"|
|CHARSET||set to the character set to be used for the output, default is utf-8|
|TEMPLATE_PREFIX||prefix for template's names|
|TEMPLATE_LOCATION||set to directory to find templates in|
|ERROR||set to a named variable to return the error state of the IDLdoc call; 0 indicates no error, anything else is an error|
|DEBUG||set to allow crashes with a stack trace instead of the default simple message|
|HELP||set to print out the syntax of an IDLdoc call|
|VERSION||set to print out the version of IDLdoc|
|N_WARNINGS||set to a named variable to return the number of warnings for the|
|LOG_FILE||if present, send messages to this filename instead of stdout|
|ASSISTANT||obsolete; no longer used|
|PREFORMAT||obsolete; no longer used|
|BROWSE_ROUTINES||obsolete; no longer used|
Producing customized output
IDLdoc uses text file templates to create its output. These can be customized to produce any kind of text output: HTML, LaTeX, DocBook, restructured text, etc. The templates are located in the "templates" directory of the distribution. But instead of modifying them directly IDLdoc provides a mechanism to provide a location to your own sets of templates with the TEMPLATE_PREFIX and TEMPLATE_LOCATION keywords.
To produce output of a different style than HTML, use the COMMENT_STYLE keyword to specify a type of output (html, rst, and latex are provided). Other styles can be created as well.