Model Documentation - openmpp/openmpp.github.io GitHub Wiki
Home > Model Development Topics > Model Documentation
This is the main topic on model documentation.
- Authored Model Documentation: The autonomous authored component of 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
- Introduction and outline
- Use cases Use cases for model documentation: end users, model developers, content developers
- The two components of model documentation Autonomous authored and the generated Symbol Reference
- Building model documentation How to build (or not) model documentation and control its content
- Using model documentation UI access, stand-alone file, searching, printing
- Exploring internals using doxygen Going down the rabbit hole of OpenM++ internals
For an immediate hands-on tour of model documentation,
build the RiskPaths model, open the model UI, and click on the 'book' icon.
For a model or content developer perspective,
open the RiskPaths project and explore the contents of the doc sub-directory containing markdown content.
The example RiskPaths model documentation is configured for model and content developers.
Model documentation has multiple audiences and multiple use-cases, and a one-size-fits-all approach is unlikely to match all of these needs well. The architecture of Model Documentation in OpenM++ is designed for flexibility and easy reconfiguration to meet one need or another, for the same model.
This topic starts with a general exposition on the principal use cases for model documentation.
It then describes the two main components of model documentation
and how they are structured into topics.
The next two subtopics describe how to build and use model documentation.
A final stand-alone subtopic describes how doxygen can be used to explore model internals,
including components normally hidden from model developers.
Model documentation has several different audiences:
Model users need to understand the model in general, including its
- substance
- methods
- intended uses
- limitations
Users who run the model also need to understand the meaning and proper use of the model symbols exposed through the user interface, run downloads, or through external tools like R or Python. Those symbols consist of exposed
- input parameters
- output tables
- entity attributes in microdata
- enumerations associated with exposed parameters, tables, and attributes.
Typically, only a subset of model symbols are exposed to model users. Model users access model documentation through the model UI, or perhaps through a stand-alone PDF or HTML 'User Edition' file built and provided by a model developer.
[back to use cases]
[back to topic contents]
Model developers need to understand all aspects of the model:
- probe the model to understand or debug issues
- understand internal relationships and dependencies among symbols and model code
- develop new functionality coherent with existing code
Model developers access model documentation through the model UI, or perhaps by directly opening a previously built HTML 'Developer Edition' file. They may also access model documentation through an IDE when working with the model source code. Typically, model developers access all of the models symbols, including symbols not directly relevant to model users such as entity sets, functions, and model code modules, as well as parameters, tables, entity attributes, and enumerations not visible to users in the UI.
[back to use cases]
[back to topic contents]
Content developers use model documentation to review and author model documentation, focusing on
- introducing the model to new users
- presenting the subject matter of the model
- reviewing the coherence and coverage of model documentation
[back to use cases]
[back to topic contents]
Model documentation consists of two components which can work independently or synergistically:
- A configurable Symbol Reference of generated cross-referenced content on parameters, tables, enumerations, etc., available in either a User Edition (default) or a Developer Edition.
- Optional autonomous authored model documentation, organized as a collection of distinct topics, which can link to each other, to topics in the Symbol Reference, or to optional downloadable supporting files.
Model documentation can consist of one of these two components, or both.
Each component consists of a collection of topics, where each topic can be the target of a link from elsewhere in the model documentation.
A topic in the Symbol Reference is either a model symbol (the topic name / link target is the symbol name), or one of several fixed topics used to navigate the Symbol Reference. The main topic of the Symbol Reference contains some tombstone information about the model and a table of links to several navigation aid topics. By default, the Symbol Reference is targeted to a model user, so it documents only those symbols which are exposed in the model UI.
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).
By default, model documentation is built and assembled as an intrinsic step in the model build. Building model documentation for a large model can take a noticeable amount of time, so a model developer might want to turn it off to speed development cycles, and turn it back on from time to time to refresh the Developer Edition of the Symbol Reference for their own use, or to build a final User Edition version of model documentation for a model release.
In Visual Studio, the Model project OpenM++ property page contains an option to turn building model documentation on or off:
In development environments using make, setting the MODEL_DOC_DISABLE variable will disable the model documentation build step.
The most recently built version of model documentation will continue to be available from the model UI, even after the model is rebuilt. If model documentation is disabled in the build, its content may not reflect the model code, and it may differ from context-sensitive help displayed in the UI.
Symbol labels and notes for symbols exposed to the user through the UI are always published, independent of build settings for model documentation. The model UI uses those labels and notes to display up-to-date context-specific information on exposed parameters, tables, attributes, and for any enumerations used by those exposed symbols.
Which of the two
documentation components
are built and assembled into the final model documentation can be controlled using the following options in model code, e.g. in the model code module code/ompp_options.ompp:
options authored_documentation = on;
options generated_documentation = on;
By default, both options are on,
and if the model has no autonomous authored content,
model documentation will consist of only the generated Symbol Reference component.
The content of the generated Symbol Reference, including the choice of User Edition or Developer Edition, can be controlled through options in model code, as described in customizing the Symbol Reference.
For each model language, the two
components of model documentation
are built and assembled into one .html file for each model language.
The UI links to this file when a user requests model documentation by clicking the 'book' icon.
The 'book' icon is available in several places in the UI:
- the landing page which lists available models
- the title bar displayed at the top of all pages
- the information pop-up for a symbol
Model documentation can take a noticeable time to load in a browser if the model is large and complex, and if the Developer Edition of the Symbol Reference is selected.
From a browser, the entire model documentation can be searched using the browser's Find on page command or Ctrl-F key combination to identify all occurrences of a word or phrase in the model documentation.
From a browser, the model documentation can be converted from .html to .pdf format by invoking the browser's Print command or Ctrl-P key combination and selecting pdf as the target printer.
Model documentation is designed so that each topic starts on a new page in the resulting .pdf file (only tested on the Microsoft Edge browser).
The .html files containing the model documentation can be accessed directly in the file system used to build the model.
They are located in a doc sub-directory of the bin directory of the model (not to be confused with the doc sub-directory of the model root, which contains authored content).
For RiskPaths, the files are
RiskPaths/.../bin/doc/RiskPaths.doc.EN.html (English)
and
RiskPaths/.../bin/doc/RiskPaths.doc.FR.html (French)
Label and note information for symbols exposed in the UI are always written to the model database for access by the UI, external utilities like dbcopy,
the oms business layer,
and (possibly) external packages written R or python using oms.
The wiki subtopic Background on doxygen mentions that the doxygen application can generate hyperlinked HTML documentation for a C++ project. After the OpenM++ compiler has run and produced the C++ code to implement a model, a complete C++ project for that model exists. Doxygen can be run with this project as input to create hyperlinked HTML documentation of the C++ code of the model. An example doxygen input file for RiskPaths is located at OM_ROOT/models/RiskPaths.doxyfile. Below is a screenshot of a browser displaying the C++ documentation produced by doxygen for RiskPaths:
The screenshot shows information for the Person member function timeUnion1DissolutionEvent() which is an event time function supplied in model code.
Note that hovering over the symbol union_duration in the model source code gives summary information about the symbol, a bit like the display in the Visual Studio IDE. Note also the References section below the function body, which lists all non-local variables used in the function with each hyperlinked to its section elsewhere in the doxygen-generated HTML documentation.
The documentation generated by doxygen for RiskPaths is based not just on model code. It is also based on C++ code generated by the OpenM++ compiler and fixed framework OpenM++ code. That code is rarely pertinent to a model developer. Future enhancements may remove those superfluous portions from doxygen output and add customized doxygen sections targetted to model developers.