API documentation for the docutils module#

This submodule contains a dataclass used to generate content for the documentation. None of the functions defined here are intended for use outside of the documentation.

Data:

RST_TO_MD

Tags to replace when converting RST descriptions of fields to Markdown.

Functions:

dump_config_toml(path, config_object)

Render a configuration class as TOML.

model_config_to_deflist(model_name, ...[, ...])

Renders the fields in a configuration class as Myst Markdown definition list.

variable_table()

Generate an HTML TABLE representation of the data variables.
virtual_ecosystem.core.docutils.RST_TO_MD = [(':cite:t:', '{cite:t}'), (':cite:p:', '{cite:p}'), (':attr:', '{attr}')]#

Tags to replace when converting RST descriptions of fields to Markdown.

virtual_ecosystem.core.docutils.dump_config_toml(path: str, config_object: Configuration) → None[source]#

Render a configuration class as TOML.

This function returns markdown providing a styled TOML representation of a Configuration subclass, including default values.

Parameters:

  • path – The configuration path to the specified configuration class.

  • config_object – A configuration class instance to render as TOML.

virtual_ecosystem.core.docutils.model_config_to_deflist(model_name: str, config_object: Configuration, display: bool = True, recurse: bool = True)[source]#

Renders the fields in a configuration class as Myst Markdown definition list.

This is a helper function for use in documenting model configurations. It takes a model configuration class and then iterates over model fields, recursing into sub-models within the fields if needed, to generate a definition list in MyST markdown.

Using this requires that the markdown document in which the output is rendered sets mystnb parsing to use render_markdown_format: myst. Myst parsing applies the class myst to the containing DL tags - the CSS of the DD and DT tags are extended by docs/source/_static/css/custom.css.

Parameters:

  • model_name – The name of the model as it would appear in a configuration file.

  • config_object – A ModelConfig instance

  • display – Should the function wrap the output using display_markdown() or simply return the markdown text to be incorporated during recursion.

  • recurse – Should the function recurse into nested models.

virtual_ecosystem.core.docutils.variable_table()[source]#

Generate an HTML TABLE representation of the data variables.

This function returns HTML with the following elements:

  • A DIV containing checkbox selectors for each registered model (apart from the toy testing model).

  • A DIV containing checkbox selectors for each role from the model variable class attributes.

  • A TABLE element containing the variable name, description, axes, units and then which models include each variable in each role.

    • 0: Column used to hold DataTables dt-control to hide/show child cells

    • 1: ‘name’, Name

    • 2: ‘unit’, Units

    • 3: ‘axis’, Axes

    • 4: ‘description’, Description

    • 5: ‘variable_type’, Variable Type

    • 6: ‘vars_required_for_init’, RI

    • 7: ‘vars_populated_by_init’, PI

    • 8: ‘vars_required_for_update’ RU

    • 9: ‘vars_populated_by_first_update’, PU

    • 10: ‘vars_updated’, Updated

The sphinx configuration is then setup to add JavaScript to the page displaying this table that adds DataTable functionality to the TABLE object and implements filtering using the checkboxes. It also hides the columns containing the model by variable role data - this is inferred from the selector checkbox settings.