26.9. Module Help Editor

A module's help is created on base of *.mhelp files. When these are edited in MATE, a number of additional, help-specific features are available: a customized GUI with special outline appearance and toolbar, syntax highlighting, and auto-completion. The goal is to keep the actual documentation generation process far from the user; for details on the workflow behind the scenes, see Section 26.9.3, “How it Works”.

The free text areas use the reStructuredText (reST) markup, see Section 26.9.2, “Formatting”. Aside of the usual formatting, two expressions are important. “Roles” refer to extensions for inline markup in reST, in our case for field and module references. “Directives” refer to extensions that add support for new constructs, in our case links to images, screenshots, and crossreferences.

To open MATE as Help Editor, either open an *.mhelp file or right-click a module and select Edit Help.

Figure 26.19. MATE for Module Help

MATE for Module Help

When editing the help file of a module, all important information of the module down to the field specifications are extracted automatically. The basic module information is therefore always available in the module help. Additional documentation should be added by the user, especially into the areas Purpose, Usage, Details, Interaction, and Tips.

The directives for screenshots (.. screenshot:: [window]) are already prepared, one entry for every window of the module. To remove the screenshot from the module help, just remove the text from the screenshot entries.

The help is aware of changes, this results in the following for field and enumeration items:


With these change-tracking mechanisms, the TestCenter can be used to test for documented fields.

For fields and enumerations, the first paragraph of the help is used as tool tip in the panels. This should be kept in mind when entering information.

The outline formatting is as follows to show the state of the documented items:

Formatting of the text can be done via the buttons in the middle of the toolbar (see Table 26.3, “Help Toolbar Buttons”), using the context menu (see Figure 26.21, “Text Context Menu”), and manually entering the markup in reST syntax (see Section 26.9.2, “Formatting”).

Generating the actual HTML help can be done with () or without () prior screenshot generation. The result is automatically displayed in the default browser.


On the first generation of the HTML help, MATE checks for screenshots being made no matter which of the two buttons above you press.

Table 26.3. Help Toolbar Buttons

Check screenshots and generate help

Opens a window first in which the screenshots to be created can be selected. For the selected screenshots, the images are created and added to the ...screenshot directives.

If the module window is open with visible data, the windows will be captured as-is; this allows for adding illustrative information via the screenshots.


Screenshots are not taken properly when using the Aero design of Windows 7. Please change to another design.

Generate HelpCompiles the help project to create HTML output, without new screenshots.
BoldFormats selected text in bold (** ** in reST syntax).
ItalicFormats selected text in italic (* * in reST syntax).
Field linkEnters field link in editor.
Module linkEnters module link in editor.
Image link Opens a dialog to browse for images relative to the mhelp folder of the module's help.
Insert cross referenceOpens a dialog in which references to other documents and sections in the MeVisLab help can be entered.
Show reSTOpens the help source in reST format in a new tab. The reST format is the base for the HTML creation, so in case of help generation problems, check this to find the problematic lines.
Show informationToggles an information area on top of the editor area. It shows information about the selected element and module.
HelpToggles a help area on top of the editor area, showing general information on how to enter contents in the help format.

26.9.1. Context Menus

Two options for the outline display are available from the context menu:

  • Needs Documentation [element]: If checked, the entry is in red italic. If not checked, the entry is in light-gray italic.

  • Hide Fields Not Needing Documentation: Hides all fields for which “Needs Documentation” is unchecked.


The context menu entry can be chosen by using the right mouse button. If you need to toggle the need for documentation for a lot of fields, just use the right mouse button to bring up the context menu and use the same right mouse button for selecting the option.

Figure 26.20. Outline Context Menu

Outline Context Menu

The context menu of the text area offers shortcuts to the three basic formatting styles bold, italic, and fixed (see below). If more than one word is selected, the formatting will be applied to all of the selection. If the cursor is placed on a word, the formatting is only applied to this word. It also offers shortcuts to format words as roles (field, module, overview) and directives (screenshot, image, image in package, cross reference), and to add new directives (images and crosslinks).

If a word is unknown to the spellchecker, it will be underlined in red. The context menu (of that word) offers known variants as a correction or to add the unknown word to the user's dictionary.

Figure 26.21. Text Context Menu

Text Context Menu

26.9.2. Formatting

For the formatting, reStructured Text (reST) syntax is used. It has some similarity with MarkUp or Wiki syntax.

The editor supports the editing process by two means: syntax highlighting of reST elements and autocompletion.

Selected formatting options:

Table 26.4. Inline markup

*text*italic text
**text**bold text
``text``fixed space text
  • bullet list

  1. numbered list

[number]. (e.g., 2.) 2. explicitly numbered list

Table 26.5. Directives


.. image::


inserts the referenced image

.. image-in-package::


inserts the referenced image from another package

.. screenshot::




inserts the screenshot (if already created) or a link to the screenshot

Example with autocompletion:

Table 26.6. Roles

:field:`(modulename.)fieldname` links to a field of a module

links to a module

Example with autocompletion:


links to an overview


links to targetptr in another document. Use "Insert Cross Reference" to insert this role (see Table 26.3, “Help Toolbar Buttons”)


links to a file in a package. This is similar to the image-in-package directive


links to a file relative to the mhelp file

:sub:`superscript`\ text

adds a superscript to the text

:sub:`subscript`\ text

adds a subscript to the text

For more information about the reST syntax, see Sphinx reStructuredText Primer.

26.9.3. How it Works

.mhelp files are written in MDL and have an MDL tree structure. They are created from the module interface definition and the GUI definition. Upon every edit initiated from a module's context menu in MeVisLab, this MDL tree is created again with all module data in the module help being updated automatically. The texts that the user adds in the actual “Edit Help” step are merged with the updated data. If the module has changed in structure, e.g., elements, fields, or enumerators are moved or renamed, this will be handled as follows: deleted elements will be removed, added elements will be added, renamed elements will be renamed and a help text will be added to the element.

Figure 26.22. Automatically Documented Elements

Automatically Documented Elements

Upon creation, the following information from module sources is extracted and added to the module help:

  • Windows: For each window of the module, an outline entry with the respective screenshot directive is added.

  • Inputs: Each input is added as outline entry. Available comments are added as documentation for the respective inputs.

  • Fields: All fields used in the GUI windows are added as outline entry (red italic). After that, all fields not visible in the GUI (“hidden”) are listed (dark-gray italic). Available tool tips will be added as documentation for the respective fields.

The conversion of the .mhelp file to HTML happens in two major steps:

  • The MDL file is converted to reStructured Text (see reST) by a core macro module .

  • In a second step, the reST format is converted to HTML via Sphinx (see Sphinx Python documentation generator). To allow every MeVisLab user to create module help, Sphinx is delivered with and integrated in MeVisLab.

The help system is implemented in MeVisLab core libraries, this makes the automatic generation of tool tips from help texts (and from tool tips to help text upon first creation of a help file) possible.

All module help source files are generated in a mhelp directory besides the module definition files to which they belong.

Resulting HTML files are put below the Documentation folder of the package.

26.9.4. Internal HTML Preview

You can tell MATE to open generated module help documents in an internal HTML view instead of the system web browser (Section 26.7, “Preferences”). The HTML view is an additional tab in the workspace:

Figure 26.23. HTML View


You can view the module help editor and the HTML view at the same time, by decoupling the HTML view from the workspace as a separate window:

Figure 26.24. HTML View Decoupling

HTML View Decoupling

By pressing the Add To Workspace button, the HTML view is returned it to the workspace:

Figure 26.25. Decoupled HTML View

Decoupled HTML View