authored model documentation - openmpp/openmpp.github.io GitHub Wiki
Home > Model Development Topics > Authored Model Documentation
How to organize, write, and incorporate the autonomous authored component of model documentation.
This topic is under construction and/or revision.
- Model Documentation: Home topic on model documentation
- Generated Model Documentation: The Symbol Reference component of model documentation
- Model Languages: The human languages supported by a model
- Model Symbols: Symbols in model code and in the user interface
- Symbol Labels and Notes: Human-language labels and notes for model symbols
Autonomous authored model documentation is one of the two components of model documentation,
the other being the generated Symbol Reference.
It is an optional component, and becomes active when appropriately-named content files are present in the model doc sub-directory.
The autonomous authored component of Model Documentation can be explicitly disabled by an option in model code:
options authored_documentation = off;Examples use the RiskPaths model which is included in OpenM++ distributions.
The autonomous authored documentation content for RiskPaths is also included in the distribution,
for both English and French.
Autonomous authored model documentation is perhaps best understood by exploring it interactively.
To do so, open the RiskPaths project, build, run, and click the 'book' icon.
Or, after building RiskPaths,
open the file RiskPaths/.../bin/doc/RiskPaths.doc.EN.html.
This subtopic walks through the autonomous authored documentation of RiskPaths, topic by topic, using a series of screenshots from a browser session.
Selected aspects of each screenshot are explained using extracts from the associated markdown content files in the RiskPaths/doc sub-directory.
These authored content files are part of the OpenM++ distribution and can be opened and viewed in an IDE.
The annotated walk-through is based on 6 browser screenshots from RiskPaths authored topics.
Links are provided to each annotation.
- Topic walk-through #1: RiskPaths Home
- Topic walk-through #2: RiskPaths Introduction
- Topic walk-through #3: RiskPaths General Description (top)
- Topic walk-through #4: RiskPaths General Description (bottom)
- Topic walk-through #5: RiskPaths First pregnancy
- Topic walk-through #6: Acceuil : RiskPaths
This topic is the Home topic of the model documentation of RiskPaths,
which is the topic displayed when a user clicks the 'book' icon in the model selection page or on the title bar at the top of the UI.
The content file for the Home topic in the model doc directory must be named Home to be recognized as such.
For RiskPaths, the English-language file is RiskPaths/doc/Home.EN.md.
The language code in the filename is required, as is the .md markdown filename extension.
[back to annotated walk-through]
[back to topic contents]
The first 2 lines of the Home topic RiskPaths/doc/Home.EN.md look like this:
# RiskPaths Home
The leading # followed by a space indicates that the line is a Level 1 Heading,
which will be rendered using a large font in the browser, as seen above.
The second line is blank.
In markdown a blank line can signal the end of one rendered portion and the beginning of the next.
Inserting a blank line between different syntactic portions can be important to obtain the desired rendering.
For example, a line which starts with #### may be treated as just a portion of a preceding paragraph instead of a heading if it is not preceded by a blank line.
[back to annotated walk-through]
[back to topic contents]
The next lines of the Home topic look like this:
RiskPaths is a simple, competing risk, case-based continuous time microsimulation model. Its main use is as a teaching tool, introducing microsimulation to social scientists and demonstrating how dynamic microsimulation models can be efficiently programmed using
[Modgen](https://www.statcan.gc.ca/microsimulation/modgen/modgen-eng.htm)
or
[OpenM++](https://openmpp.org/)
.
The
[OpenM++ wiki documentation](https://github.com/openmpp/openmpp.github.io/wiki)
uses RiskPaths extensively in examples.The content of the paragraph is split into several lines in the markdown source. The first line is long. The remainder of the paragraph was split into several lines to make it easier to see and edit the hyperlinks in the paragraph (described below). All of these lines are assembled and rendered in the browser as a single paragraph.
The line which starts with . illustrates a forced line break in markdown.
It is not apparent above, but that line actually consists of 3 characters,
a . followed by 2 spaces.
In markdown, a line which ends with 2 or more spaces forces the following text to start on a new line.
Markdown syntax usually renders content appropriately in the browser,
so hard line breaks are rarely needed.
[back to annotated walk-through]
[back to topic contents]
The first paragraph contains three external links.
The third renders as OpenM++ wiki documentation with hyperlink highlighting and mouse-over behaviour.
Here's the associated markdown source from RiskPaths/doc/Home.EN.md:
The
[OpenM++ wiki documentation](https://github.com/openmpp/openmpp.github.io/wiki)
uses RiskPaths extensively in examples.The text in brackets is displayed as the link, and the target of the link follows immediately after in parentheses.
[back to annotated walk-through]
[back to topic contents]
Immediately below the first paragraph is the heading Symbol Reference,
which is not only a heading but also an internal link to a topic elsewhere in the RiskPaths model documentation.
Here's the associated source in RiskPaths/doc/Home.EN.md:
#### [Symbol Reference](#symbol-reference)The 4 leading # characters indicate a level-4 heading.
The internal link which follows displays as Symbol Reference,
followed by the target of the link in parentheses.
Note that the target of the internal link contains no protocol or path, and starts with the # character,
followed by the topic name.
The target of the internal link is the special topic symbol-reference,
which is the main page of the Symbol Reference for the model.
It's generally a good idea to include a link to the Symbol Reference
in the Home page of autonomous authored documentation
so that it's only one click away for users.
[back to annotated walk-through]
[back to topic contents]
The immediately following paragraph starting with Cross-referenced information... is block-indented with respect to the Symbol Reference heading, using a leading > character.
Here's the associated markdown:
#### [Symbol Reference](#symbol-reference)
> Cross-referenced information about the symbols of Riskpaths, including its
[parameters](#parameter-hierarchy),
[tables](#table-hierarchy),
and
[enumerations](#enumerations-alphabetic).That extract illustrates internal links to the three main navigation aids in the Symbol Reference. Those links were included to make Symbol Reference navigation aids only one click away for a returning user.
[back to annotated walk-through]
[back to topic contents]
Moving down the page, the next heading Introduction is an internal link to a different topic in the autonomous authored documentation.
Here's the associated markdown source,
again from RiskPaths/doc/Home.EN.md:
#### [Introduction](#001-Introduction)The topic name is 001-Introduction.
That internal topic name was created when the OpenM++ compiler processed documentation files in the RiskPaths/doc directory.
The doc directory contained the file 001-Introduction.EN.md.
That file has the extension .EN.md,
which the OpenM++ compiler recognized as the English-language markdown content for an internal topic to be named 001-Introduction.
The
next screenshot
shows that topic.
Two other headings Model Substance and Model Implementation follow to serve as a clickable table of contents to the authored RiskPaths documentation.
[back to annotated walk-through]
[back to topic contents]
Towards the bottom of the page is a section `Additional Resources', whose markdown source is:
#### Additional resources
> A discussion of microsimulation by the author of RiskPaths, Martin Spielauer, c. 2008, in PDF format:
* [Chapter 1: What is Dynamic Social Science Microsimulation?](chap1-eng.pdf)
* [Chapter 2: Microsimulation Approaches](chap2-eng.pdf)
* [Chapter 3: Exploring the Model RiskPaths](chap3-eng.pdf)
* [Chapter 4: RiskPaths from the Model Developer's View](chap4-eng.pdf)
This documentation is based on extracts from chapters 3 and 4.Notice that the target of the 4 links have no protocol or path,
and do not start with the # character.
These links are to downloadable copies of .pdf files whose originals are located in the RiskPaths/doc directory.
They were copied during documentation build to a location suitable for subsequent download by a model user.
For example, a copy of the file RiskPaths/doc/chap1-eng.pdf can be downloaded by a model user by clicking on the link
[Chapter 1: What is Dynamic Social Science Microsimulation?](chap1-eng.pdf)
in model documentation.
This can be a convenient way to make stand-alone .pdf documents available for download from the model UI, without needing to stage the file to a web site.
[back to annotated walk-through]
[back to topic contents]
At the bottom of the page is a single link to move to the Next authored topic.
The markdown source is:
[[Next >>](#001-Introduction)]The page navigation links are displayed with enclosing brackets as a visual aid,
so the entire link is enclosed in brackets in the markdown source.
The next authored topic in RiskPaths is Introduction,
whose screenshot is below.
[back to annotated walk-through]
[back to topic contents]
At the bottom of the page are two links,
one for Home and one for Next.
The markdown source is:
[[Home](#Home)] [[Next >>](#002-General-description)]The current topic name is 001-Introduction,
so the next topic is 002-General-description.
The 3-digit number prefix in the topic name / filename aids in constructing the navigation links correctly.
[back to annotated walk-through]
[back to topic contents]
A bulleted list with 4 items appears partway down the topic.
The associated markdown content in RiskPaths/doc/002-General-description.EN.md is:
For unions, we distinguish four possible state levels:
- single
- the first three years in a first union
- the following years in a first union
- all the years in a second union
Items in a bulleted list can start with -, *, or +,
which are treated identically.
Bulleted lists can be nested using leading spaces (not illustrated here).
Note the empty line between the preceding paragraph and the first entry in the list.
This is required for the list to be recognized as such.
Otherwise, markdown would consider the line - single to be a continuation of the previous paragraph.
[back to annotated walk-through]
[back to topic contents]
At the bottom of the page are three links,
one for Home, one for Prev, and one for Next.
The markdown source is:
[[Home](#Home)] [[<< Prev](#001-Introduction)] [[Next >>](#003-First-pregnancy)]The current topic name is 002-General-description,
so the previous topic is 001-Introduction,
and the next topic is 003-First-pregnancy.
The 3-digit number prefix in the topic name / filename aids in constructing the navigation links correctly.
[back to annotated walk-through]
[back to topic contents]
This RiskPaths topic contains two tables.
The markdown content for the first table (in RiskPaths/doc/003-First-pregnancy.EN.md) is:
**Table 1: First pregnancy risks**
|table>
| Bulgaria | Russia
- | - | -
15-17.5 | 0.2869 | 0.2120
17.5-20 | 0.7591 | 0.7606
20-22.5 | 0.8458 | 0.8295
22.5-25 | 0.8167 | 0.6505
25-27.5 | 0.6727 | 0.5423
27.5-30 | 0.5105 | 0.5787
30-32.5 | 0.4882 | 0.4884
32.5-35 | 0.2562 | 0.3237
35-37.5 | 0.2597 | 0.3089
37.5-40 | 0.1542 | 0.0909
|<table
The table title is enclosed in **,
which in markdown means to bold it.
The markdown syntax for tables differs from typical markdown syntax.
It follows the syntax of the
maddy
component used in OpenM++.
In particular
- A table starts with the exact string
|table>, on its own line. - The separator between table heading rows and table body rows is the exact string
- | - | -, on its own line. - The table ends with the exact string
|<table, on its own line.
Note that in header and body rows,
the | character is a column separator,
not a column delimiter.
In other words, there is no leading | at the start of a row,
and no trailing | at the end of a row.
If one is included, an additional empty column will be created.
[back to annotated walk-through]
[back to topic contents]
To display the French language version of the RiskPaths autonomous model documentation,
return to the UI, switch languages using the drop-down menu in the upper right,
select Français,
then click the book icon on the title bar.
Alternatively,
open the file RiskPaths/.../bin/doc/RiskPaths.doc.FR.html.
The names of autonomous authored topics can be identical for all the languages of a model.
For example, the Home topic of RiskPaths is named Home in both the English and French versions of the documentation.
This does not impact the fidelity or completeness of human-language versions of autonomous authored model documentation
because topic names are not rendered on the browser page.
For example, the English version of the "First Union Formation" topic is in the file
RiskPaths/doc/004-First-union-formation.EN.md
and the French language version is in the file
RiskPaths/doc/004-First-union-formation.FR.md.
For both languages, the topic is named
004-First-union-formation
and that's what's used for link targets in both languages,
for example in the RiskPaths Home topic.
Other approaches to naming autonomous authored topics are possible,
but maintaining identical topic names across languages aids maintenance of A) the translation (the filenames in the doc directory sort together),
and B) the link structure (the link targets are identical in all languages).
It is important to have a translated version of each autonomous authored markdown file in the model doc directory.
Otherwise, links in autonomous authored content may be 'dead',
i.e. clicking them does nothing because the link target is absent in the .html.
The directory RiskPaths/doc, for example contains
001-Introduction.EN.md, 001-Introduction.FR.md,
002-General-description.EN.md, 002-General-description.FR.md,
etc.
[back to annotated walk-through]
[back to topic contents]
The non-linguistic markdown content of the French language version of the RiskPaths Home topic is nearly identical to the English language version.
For example, the English language version of the link to the RiskPaths Symbol Reference in
RiskPaths/doc/Home.EN.md is:
#### [Symbol Reference](#symbol-reference)
> Cross-referenced information about the symbols of Riskpaths, including its
[parameters](#parameter-hierarchy),
[tables](#table-hierarchy),
and
[enumerations](#enumerations-alphabetic).and the French language version in
RiskPaths/doc/Home.FR.md is:
#### [Recueil des symboles](#symbol-reference)
> Renseignements recoupés sur les symboles de Riskpaths, y compris les
[paramètres](#parameter-hierarchy),
[tableaux](#table-hierarchy),
et
[énumerations](#enumerations-alphabetic).Note that the internal link targets are identical in both languages.
All that differs is the text displayed for the links.
The OpenM++ compiler uses the appropriate language-specific content
when it builds the two language-specific versions of model documentation
in the two distinct language-specific .html files.
[back to annotated walk-through]
[back to topic contents]
It may be appropriate to change external links to be language-specific. For example, the "Additional Resources" section of the Home topic in English is:
#### Additional resources
> A discussion of microsimulation by the author of RiskPaths, Martin Spielauer, c. 2008, in PDF format:
* [Chapter 1: What is Dynamic Social Science Microsimulation?](chap1-eng.pdf)
* [Chapter 2: Microsimulation Approaches](chap2-eng.pdf)
* [Chapter 3: Exploring the Model RiskPaths](chap3-eng.pdf)
* [Chapter 4: RiskPaths from the Model Developer's View](chap4-eng.pdf)
This documentation is based on extracts from chapters 3 and 4.
The original source of this material was a
[section of the Statistics Canada web site](https://www.statcan.gc.ca/en/microsimulation/modgen/modgen). and in French is:
#### Ressources additionelles
> Un discours sur la microsimulation par l'auteur de RiskPaths, Martin Spielauer, c. 2008, en format PDF :
* [Chapitre 1 : Qu’est-ce la microsimulation dynamique en sciences sociales ?](chap1-fra.pdf)
* [Chapitre 2 : Approches de microsimulation ](chap2-fra.pdf)
* [Chapitre 3 : Exploration du modèle RiskPaths](chap3-fra.pdf)
* [Chapitre 4 : RiskPaths du point de vue du développeur de modèles](chap4-fra.pdf)
Cette documentation est fondée sur des extraits des chapitres 3 et 4.
La source d'origine de ce materiel est une
[section du site web de Statistiques Canada](https://www.statcan.gc.ca/fr/microsimulation/modgen/modgen). Notice that the link to the "Chapter 1" downloadable resource in the English Home topic is
chap1-eng.pdf
while in the French Home topic it is
chap1-fra.pdf.
Both files are present in the RiskPaths/doc directory, and both are staged for possible download when the model is built.
The language-specific versions of the RiskPaths Home topic
RiskPaths/doc/Home.EN.md and
RiskPaths/doc/Home.FR.md
have been customized to link to the downloadable resource based on the language of the Home topic.
This works for RiskPaths because there are language-specific versions of those downloadable resources.
Language customization is also done in the RiskPaths Home topic for the external web link to the Modgen page on the StatCan website.
In the English-language RiskPaths Home page, the link is
[section of the Statistics Canada web site](https://www.statcan.gc.ca/en/microsimulation/modgen/modgen)
and in the French-language version the link is
[section du site web de Statistiques Canada](https://www.statcan.gc.ca/fr/microsimulation/modgen/modgen)Notice the slight difference in the two URLs: in English /en/ and in French /fr/.
If the user clicks the link from the English Home topic,
it will direct to the English-language Modgen page on the StatCan web site.
If the user clicks the link from the French Home topic,
it will direct to the French-language Modgen page on the StatCan web site,
[back to annotated walk-through]
[back to topic contents]
The
A topic in autonomous authored documentation is a .md markdown file in the model's doc sub-directory (the topic name / link target is the stem of the filename of the corresponding .md markdown file).
If present, the Home authored document becomes the main (first) topic of model documentation.
Other autonomous authored topics follow in lexicographic order by topic name (same order as filename).
This subtopic describes how to compose content for both the autonomous authored component of model documentation, and for symbol notes. It contains the following sections:
The text of a note can contain formatting indicators which control how the text is rendered. The OpenM++ UI recognizes markdown formatting in a note when it displays it in the UI. For an overview of basic markdown syntax with examples, please see Markdown Basic Syntax
[back to writing content]
[back to topic contents]
A topic can contain the special embedded construct GetLabel(SymbolName)
where SymbolName is the name of a model symbol.
The OpenM++ compiler will expand the embedded construct to the label of the named symbol
in each human language version of the note.
For example, in the human language EN,
GetLabel(SimulationCases) in the body of a Note will expand to
Number of cases in run (over all members).
[back to writing content]
[back to topic contents]
Generated model documentation
contains a topic for each published symbol in a model
which can be the target of a topic link elsewhere in the generated model documentation.
A note can contain topic links.
A topic link follows the markdown conventions commonly used in wikis: [Text](#SymbolName).
The Text portion is displayed using link highlighting.
The SymbolName portion gives the target of the topic link and is not displayed.
Here's an example:
/*NOTE(model, EN)
A series of OzProj model versions accompany the on-line course "Practical Microsimulation".
...
Detailed mortality rates are given in the parameter [MortalityRate](#MortalityRate)
which has label "GetLabel(MortalityRate)"
and can also be linked from [GetLabel(MortalityRate)](#MortalityRate).
...
*/
This example contains two topic links.
The text of the first topic link is MortalityRate.
The text of the second topic link is the label of MortalityRate.
The target of both topic links is the same,
namely the topic for the parameter MortalityRate in the generated model documentation.