Automatically documenting IDL

Automatically documenting IDL can be done by placing specially formatted comments in your IDL source files, and then asking sphinx to automatically read those comments from source.

Source documentation format

There is a very simple IDL source documentation parser implemented in parser.py, which will scan your IDL source files and extract docstrings by looking for comments which immediately preceede a function or procedure definition. It will use these comments as the restructured-text formatted documentation for that function or procedure. For example, an IDL file bench_view.pro containing this will produce automatic documentation for a procedure named bench_view:

;+
; Display diagnostic windows which show the current state of the test bench.
;
; Views:
;
; - :pro:`bench_wfs_view`
; - :pro:`bench_dms_view`
; - :pro:`psf_view`
;
; :keyword NOPSF: Prevent taking a PSF image.
; :keyword TB: The test bench state structure. (see :func:`get_test_bench`)
;-
pro bench_view, NOWFS=NOWFS, NOPSF=NOPSF, TB=TB
  compile_opt idl2
  TB = get_test_bench(TB=TB)
  if ~keyword_set(NOWFS) then r=bench_phase(TB=TB)
  bench_wfs_view, TB=TB
  bench_dms_view, TB=TB
  if ~keyword_set(NOPSF) then psf_view, TB=TB
end

Note

Any comment which directly precedes the procedure or function definition will be used. The IDL continuous comment style (;+ and ;-) is not required for the parser to recognize it as a docstring. Note that the docstrings are formatted in restructured text, and not the IDLDOC format.

Source inclusion directives

To generate documentation from your IDL soruce file, add one of the following directives to your restructured text documentation. Both directives accept a path relative to the documentation root folder.

.. idl:autofile:: path/to/idl/file.pro

Include automatically generated documentation from an IDL file at path/to/idl/file.pro.

The option :summary: includes a table summary of all functions in a file at the beginning.

The option :absolute: can be used to require an absolute file path.

.. idl:autopath:: path/to/directory/of/idl/files/

Include automatically generated documentation for every IDL file (*.pro) in the given path.

The option :summary: includes a table summary of all functions in the files at the beginning of the documentation.

The option :absolute: can be used to require an absolute file path.