Customize documentation templates

Published

March 6, 2024

Edit templates that get used for model documentation or for validation reports to configure templates for specific use cases or where the existing templates supplied by ValidMind need to be customized.

About documentation templates

Documentation templates are stored as YAML files that you edit directly in the online editor. These templates are versioned and saving a documentation template after making changes or reverting to a previous version state always creates a new version.

Prerequisites

The template you want to edit must have been added to the ValidMind Platform already.

If you are not sure which template or which version of a template your model documentation is using, check the Documentation page of your model. The Document Template section in the right sidebar lists the information.

Template schema

Schema Docs
Type: object

root template_id
Type: string

Unique identifier for the template.

root template_name
Type: string

Name of the template.

root version
Type: string

Version of the template.

root description
Type: string

Description of the template.

root sections
Type: array

Documentation sections of the template.

Each item of this array must be:

root sections section
Type: object

root sections sections items id
Type: string

Unique identifier for the section.

root sections sections items title
Type: string

Title of the section.

root sections sections items description
Type: string

Description of the section.

root sections sections items parent_section
Type: string

ID of the parent section.

root sections sections items order
Type: integer

Order of the section in the navigation menu. By default sections are ordered alphabetically. If order is specified, sections will be ordered by the order value, and then alphabetically.

root sections sections items default_text
Type: string

Default text for the section. If set, a metadata content row will be created with this text when installing the template

root sections sections items index_only
Type: boolean

If true, the section will be displayed in the navigation menu, but it will not be accessible via direct link.

root sections sections items condensed
Type: boolean

If true, the section will condense all of its subsections into a single section.

root sections sections items guidelines
Type: array of string

Documentation or validation guidelines for the section.

Each item of this array must be:

root sections sections items guidelines guidelines items
Type: string

root sections sections items contents
Type: array

Contents to be displayed on the section.

Each item of this array must be:

root sections sections items contents section_contents
Type: object

Single content block of the module.

root sections sections items contents contents items content_type
Type: enum (of string) Default: "metadata_text"

Must be one of:

  • "metadata_text"
  • "dynamic"
  • "metric"
  • "test"

Examples:

"metadata_text"

"test"

root sections sections items contents contents items content_id
Type: string

ID of the content to be displayed for the given content type (text, metric, testm, etc.).
Examples:

"sample_text"

"section_intro"

root sections sections items contents contents items options
Type: object

Options for the content block.
Examples:

{
    "default_text": "This is a sample text block."
}

{
    "metric_id": "metric_1",
    "title": "Custom Title for Metric 1"
}

{
    "test_id": "adf_test"
}

root sections sections items contents contents items options default_text
Type: string

Default text for the content block. Only applicable for metadata_text content blocks.

root sections sections items contents contents items options title
Type: string

Title of the content block. Only applicable for metric and test content blocks.

Steps

  1. Log in to the ValidMind UI.

  2. On the Settings page, click Templates.

  3. Select one of the tabs for the type of template you want to edit:

    • Documentation Templates
    • Validation Report Templates

  4. Locate the template to edit and, at the bottom of the template card, click Edit Template.

  5. In the YAML editor that opens, make your changes.

    • Use See changes to view a side-by-side comparison of your changes with the latest version of the template.
    • Use Reset changes to delete your changes and return to the latest version of the template.

  6. Click Prepare new version to save your changes.

    • Add a description in Version notes to track the changes that were made once the version is saved.

After you have saved a new version, it becomes available for use with model documentation or validation reports.

Troubleshooting

The documentation template editor validates the YAML changes you make and flags any errors that it finds. If you make a change that the editor cannot parse correctly, the editor will not let you save the changes until you correct the YAML.

Common issues with YAML include incorrect indenting, imbalanced quotes, or missing colons between keys and values. If you run into issues with incorrect YAML, check the error message provided by the template editor, as it might provide a line and column number where the error occurs.