Improve rst markup support about idldoc HOT 8 OPEN

Changeset r481 adds images to rst markup and links should be easy now.

from idldoc.

Author: mpiper
I'd like to ask for an enhancement to the rst form for the '''Examples''' tag.
I'd like this form:

; :Examples:
;   IDL> ; A comment
;   IDL> foo

to place pre tags (or use a monospaced font with line breaks) around the example code in the output, like this:

=== Examples ===

IDL> ; A comment
IDL> foo

from idldoc.

So, you mean

; :Examples:
;    Try this example::
;
;       IDL> ; A comment
;       IDL> foo

is too wordy? I'm not sure I want the Examples section to not have any "regular" text. For example, I could have an Examples section that has some explanation in it:

; :Examples:
;    Run the main-level program at the end of this file for an example of using MG_THEMERIVER::
; 
;       IDL> .run mg_themeriver
; 
;    This should produce a result like .. image:: themeriver.png

from idldoc.

Author: mpiper
Aha! I didn't read the documentation carefully enough -- I now see how the double colon works.

from idldoc.

Replying to [comment:7 mpiper]:

Aha! I didn't read the documentation carefully enough -- I now see how the double colon works.

The IDL format does do that since there is no double colon markup; everything in the EXAMPLE section is treated as code.

from idldoc.

Also, add special text in backticks, i.e., routine. Maybe this looks up in the index and makes a link to it?

from idldoc.

r642 adds three levels of heading for rst markup (particularly useful in overviews, .idldoc files, directory overviews, and file comments).

from idldoc.

r652 adds some basic links. Uses "my_routine" and "text http://michaelgalloy.com" notation with backticks.

from idldoc.