Documentation Facet
Introduction
The documentation language allows you to document your language structure. The documentation will be instantly available to the users of your language's structure model through information popup dialogs (aka tootips) and a dedicated Documentation Tool window. Additionally, the documentation can be also generated into HTML javadoc-style documentation.
How to start
Enabling documentation for your language is fairly easy:
Navigate to Module Properties of your language.
Enable the Documentation facet in the Facets tab.
Choose the desired output directory for your generated documentation and close the dialog with either "Apply" or "OK".
Now you are set up to add documentation to any concept definition in the structure model of your language. Use the Add Documentation intention from the intention menu while the concept is open in the editor.
Writing documentation
There are several languages involved in documenting languages. Namely the jetbrains.mps.lang.core.doc language, the jetbrains.mps.lang.docText language and mostly the jetbrains.mps.lang.text language, in which the actual text of the documentation is expressed. You can either import these languages separately or import the jetbrains.mps.devkit.documentation devkit.
The jetbrains.mps.lang.text language, which allows you to create the actual text, consists of several essenntial concepts:
Word
Represent individual words. You can change the style of a word (bold, italic, or underlined) and optionally add a URL link. This is all set in the Inspector tool window for an individual word.
Shortcuts and MarkDown syntax are also available to set styles on individual words as well as on larger portions of text (press Enter to have the MarkDown style applied to a word).
Italics (Control + I) - *word* or _word_
Bold (Control + B) - **word** or __word__
Bold Italics - ***word*** or ___word___
Underlined (Control + U) - ~~word~~
The URL can be added to a word either in the Inspector tool window or using the Add URL intention.
References to nodes can also be inserted into the documentation text. Simply type the name of the node to reference and the completion menu will offer you all the matching available nodes:
To insert code into the documentation text, type ``` and then press space. You will see an empty field that can hold code (aka an MPS node).
Then press Control + Space and select the desired node from the completion menu.
Lines
You have the flexibility to select from various line types:
To change the line type, you can pick one from the Intentions menu or employ a specific syntax or a shortcut.
Element | MarkDown Syntax | Shortcut |
|---|---|---|
Header1 | # H1 | Control + 1 |
Header2 | ## H2 | Control + 2 |
Header3 | ### H3 | Control + 3 |
Header4 | #### H4 | Control + 4 |
Header5 | ##### H5 | Control + 5 |
Header6 | ###### H6 | Control + 6 |
Header1 | Control + 0 |
Lists
Both bullet and numbered lists are available. You can use MarkDown or intentions to set or change the list style to a line.
Element | MarkDown Syntax |
|---|---|
Bullet line | - line |
Numbered line | 1. line |
Viewing documentation
To see a popup dialog with documentation simply hower your mouse over a reference to the concept or press F1 when the cursor is on the reference.
Generating documentation
Click on the structure aspect model in the Logical View and select Preview Generated Documentation from the list.
All the generated html and css files will be saved in the folder selected in the Documentation Facet tab of the language's Module Properties dialog.
The generated documentation will contain one index file and then html files for all concepts in the language's structure model.
