generated model documentation - openmpp/openmpp.github.io GitHub Wiki

Home > Model Development Topics > Generated Model Documentation

This topic describes one of the two components of model documentation: the generated Symbol Reference.

This topic is under construction and/or revision.

Related topics

Topic contents

Introduction and outline

Model Documentation has two components: An autonomous authored component and a generated Symbol Reference component. This topic describes the latter.

Human-language labels and notes for model symbols are combined with symbol metadata and cross-reference information to produce a Symbol Reference for a model. There are two versions of the Symbol Reference, one targeted to model users and one to model developers. Each version can be customized using options statements in model code.

The User Edition of the Symbol Reference is targeted to model users. It documents all symbols exposed to users and deliberately excludes aspects of a model not exposed to users. Here are some examples of aspects excluded in the User Edition:

  • Parameters deliberately suppressed from the UI using parameters_retain.
  • Derived parameters
  • Enumerations used only in model code
  • Entity Table filters
  • Attributes not exposed to users
  • Modules
  • cross-reference information on symbol use in model code

The Developer Edition of the Symbol Reference is targeted to model developers. It includes all content in the User Edition, and adds symbols, topics and topic sections for aspects of a model not exposed to users. For example, the Developer Edition includes a topic which lists all model code modules, as well as a topic for each module.

Independent of the Symbol Reference, labels and notes for all symbols exposed in the model UI are published to the model database, for all human languages declared in the model.

The Symbol Reference component of Model Documentation can be disabled by an option in model code:

options generated_documentation = off;

[back to topic contents]

Symbol Reference - User Edition

To explore the User Edition of the Symbol Reference for RiskPaths, turn off Developer Edition by commenting the following line in RiskPaths/code/ompp_options.ompp so that it looks like this:

//options symref_developer_edition = on;

Next, rebuild the model, run it, click the 'book' icon, and from the RiskPaths Home topic click Symbol Reference.

The browser should look like this:

By default, a model's Symbol Reference documents only symbols which are exposed to users. Labels and notes for model symbols which are not available to users when the model is run are not published, and are not present in the Symbol Reference. This includes parameters and tables suppressed from the model at build time and associated classifications, ranges, and partitions not used by other published symbols. Information on attributes is published only if the model was built with microdata output enabled using the statement:

options microdata_output = on;

Symbol Reference - Developer Edition

To explore the Developer Edition of the Symbol Reference for RiskPaths, turn on Developer Edition by uncommenting the following line in RiskPaths/code/ompp_options.ompp so that it looks like this:

options symref_developer_edition = on;

Next, rebuild the model, run it, click the 'book' icon, and from the RiskPaths Home topic click Symbol Reference.

The browser should look like this:

RiskPaths Symbol Reference (Developer Edition)

The Developer Edition of the Symbol Reference augments the User Edition as follows:

  • Topics for unpublished parameters, tables, attributes, and enumerations.
  • Cross-reference tables in each symbol topic.
  • Module topics

[back to topic contents]

Customizing the Symbol Reference

Options which suppress the main topic:

Option Default Effect if changed from default
symref_main_topic on Removes the main topic including the navigation aid table.
symref_model_symbol on Removes the topic for the unique model symbol, if declared in the model.

Options which suppress navigation aids:

Option Default Effect if changed from default
symref_parameters_alphabetic on Removes the parameters alphabetic list topic.
symref_parameter_major_groups on Removes the parameter major groups topic.
symref_parameter_hierarchy on Removes the parameter hierarchy topic and parameter hierarchy breadcrumbs.
symref_tables_alphabetic on Removes the tables alphabetic list topic.
symref_table_major_groups on Removes the table major groups topic.
symref_table_hierarchy on Removes the table hierarchy topic and table hierarchy breadcrumbs.
symref_attributes_alphabetic on Removes the attributes alphabetic list topic.
symref_enumerations_alphabetic on Removes the enumerations alphabetic list topic.

Options which suppress individual topics:

Option Default Effect if changed from default
symref_topic_parameters on Removes parameter topics and parameter cross-reference sections in other topics.
symref_topic_tables on Removes table topics and table cross-reference sections in other topics.
symref_topic_attributes on Removes attribute topics.
symref_topic_enumerations on Removes enumeration topics and enumeration cross-reference sections in other topics.

Options controlling symbol notes:

Option Default Effect if changed from default
symref_topic_notes on Removes the note sections of all symbol topics.
symref_topic_notes_early on Places notes after other sections in symbol topics.
symref_topic_note_heading on Suppresses the Note: heading in symbol topics.

Options affecting only the Developer Edition:

Option Default Effect if changed from default
symref_developer_edition off Turns on symbols not exposed to users and appends "(Developer Edition)" to title in main topic.
symref_unpublished_symbols on Removes unpublished symbols, e.g. those absent due to parameters_retain or tables_retain statements in model code.
symref_global_functions on Removes global function cross-reference sections in symbol topics.
symref_entity_functions on Removes entity function cross-reference sections in symbol topics.
symref_identity_attributes on Removes identity attribute cross-reference sections in symbol topics.
symref_topic_entity_sets on Removes entity set alphabetic list, topics, and cross-reference sections in symbol topics.
symref_topic_modules on Removes module alphabetic list, topics, and cross-reference sections in symbol topics.
symref_topic_modules_use off Includes use module topics.
symref_topic_modules_symbols_declared on Turns off the alphabetic "symbols declared" section in individual module topics.
symref_topic_attributes_internal on Turns off attribute topics for internally-generated attributes, including derived attributes.

[back to topic contents]

Navigation Aid Topics

The following table lists navigation aid topics in the Symbol Reference.

Navigation aid Topic name Description and notes
Symbol Reference symbol-reference The Symbol Reference main topic.
Parameters in alphabetic order parameters-alphabetic
Parameter hierarchy parameter-hierarchy Present if the model has at least one published parameter group. May contain a trailing 'Orphan parameters' group.
Parameter major groups parameter‑major‑groups Present if parameter hierarchy present.
Tables in alphabetic order tables-alphabetic
Table hierarchy table-hierarchy Present if the model has at least one published table group. May contain a trailing 'Orphan tables' group.
Table major groups table-major-groups Present if table hierarchy present.
Enumerations in alphabetic order enumerations‑alphabetic
Modules in alphabetic order modules-alphabetic
Attributes in alphabetic order attributes-alphabetic
Entity sets in alphabetic order entity-sets-alphabetic

Note that derived parameters published as tables group with tables in the navigation aid topics, not with parameters.

[back to topic contents]

⚠️ **GitHub.com Fallback** ⚠️