Improve rst markup support

[mgalloy]

The rst markup was only partly implemented for IDLdoc 3.0. Missing markup that should be implemented:

• lists (numbered, bulleted, and definition)
• emphasis and bold
• inline code
• links: single word and phrase links (HTML and internal links)
• images
• tables

There is other markup that is not as important for header documentation that could also be implemented for a separate ticket later.

[mgalloy]

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

[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

[mgalloy]

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

[mpiper]

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

[mgalloy]

Replying to 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.

[mgalloy]

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

[mgalloy]

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

[mgalloy]

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