Generated Model Documentation

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

• Model Documentation: Home topic on model documentation
• Authored Model Documentation: The autonomous authored component of model documentation
• Model Symbols: Symbols in model code and in the user interface
• Symbol Labels and Notes: Human-language labels and notes for model symbols

Topic contents

• Introduction and outline
• Symbol Reference - User Edition
• Customizing the Symbol Reference
• Symbol Reference - Developer Edition
• Navigation Aid Topics

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:

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]