| 26.9. Module Help Editor | ||
|---|---|---|
 | Chapter 26. MATE |  |
| 26.9. Module Help Editor | ||
|---|---|---|
| | Chapter 26. MATE | |
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.
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:
Field is added: field is marked as new and needing documentation.
Field is removed: documentation text is kept but marked as being removed. Previously written help text is stored in the .mhelp file but will not be visible in the resulting HTML help.
Field is renamed: if the field name is deprecated, the text is copied. (Otherwise, the system sees the rename as an adding and removal of fields, so documentation text needs to be moved to the new field manually.)
![[Tip]](images/tip.png) | Tip |
|---|---|
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:
red italic: User-added documentation still missing.
black bold: User-added documentation exists.
light-gray italic: Element with “Needs documentation” unchecked.
dark-gray italic: Fields not visible in the GUI.
dark-gray italic bold: Fields not visible in the GUI, for which user-added documentation exists.
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.
| Tip |
|---|---|
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
| Button | Description | Explanation | |||
|---|---|---|---|---|---|
| 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 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.
| |||
| Generate Help | Compiles the help project to create HTML output, without new screenshots. | |||
 | Bold | Formats selected text in bold (** ** in reST syntax). | |||
 | Italic | Formats selected text in italic (* * in reST syntax). | |||
 | Field link | Enters field link in editor. | |||
 | Module link | Enters 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 reference | Opens a dialog in which references to other documents and sections in the MeVisLab help can be entered. | |||
 | Show reST | Opens 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 information | Toggles an information area on top of the editor area. It shows information about the selected element and module. | |||
 | Help | Toggles a help area on top of the editor area, showing general information on how to enter contents in the help format. |
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.
| Tip |
|---|---|
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. |
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.
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
| Markup | Output |
|---|---|
*text* | italic text |
**text** | bold text |
``text`` | fixed space text |
* |
|
#. |
|
[number]. (e.g., 2.) | 2. explicitly numbered list |
|
|
|
|
Table 26.5. Directives
| Directive | Effect |
|---|---|
|
| inserts the referenced image |
|
| inserts the referenced image from another package |
|
or
| inserts the screenshot (if already created) or a link to the screenshot Example with autocompletion:
|
Table 26.6. Roles
| Role | Effect |
|---|---|
:field:`(modulename.)fieldname` | links to a field of a module |
:module:`modulename` | links to a module Example with autocompletion:
|
:overview:`overviewname` | links to an overview |
:cross-ref:`document/targetptr` | links to targetptr in another document. Use "Insert Cross Reference" to insert this role (see Table 26.3, “Help Toolbar Buttons”) |
:file-in-package:`packageIdentifier.relative/path/to/file` | links to a file in a package. This is similar to the image-in-package directive |
:relative-link:`relative/path/to/file` | 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.
.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.
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.
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:
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:
By pressing the Add To Workspace button, the HTML view is returned it to the workspace:
© 2023 MeVis Medical Solutions AG
| |  | |
| 26.8. Python Debugger |  | 26.10. Session Management |
![[Note]](images/note.png)
