Documentation Facet

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.

Enabling documentation for your language is fairly easy:

1. Navigate to Module Properties of your language.

2. Enable the Documentation facet in the Facets tab.

   

3. Choose the desired output directory for your generated documentation and close the dialog with either "Apply" or "OK".

   

4. 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.

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. This language consists of several 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

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.

A Documentation Tool Window is also available. It instantly shows the documentation for the concepts under the cursor.

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.