diff --git a/README.md b/README.md index f87db708a..f6a5de70f 100644 --- a/README.md +++ b/README.md @@ -138,6 +138,51 @@ These directories may have sub-directories depending on their size and grouped s - `notebooks` — This is where notebooks retrieved from the [`validmind-library` repo](https://github.com/validmind/validmind-library) live. - `tests` — This is where test descriptions generated from the Python source in the [`validmind-library` repo](https://github.com/validmind/validmind-library) live. +### Generated documentation + +Some documentation content is auto-generated from backend source files. These scripts ensure the docs stay in sync with the codebase. + +#### Permissions documentation + +The permissions tables in `site/guide/configuration/manage-permissions.qmd` are auto-generated from the backend source files. To regenerate: + +```bash +python scripts/generate_permissions_docs.py +``` + +**Requirements:** +- The `backend` repo must be cloned at `../backend/` relative to this repo +- Python 3.9+ + +The script reads from: +- `backend/src/backend/templates/platform_resources/data.json` — resource and action definitions +- `backend/src/backend/templates/platform_resources/org_initials.json` — role permission assignments + +Output: `site/guide/configuration/_permissions-generated.qmd` + +Run this script when backend permission definitions change to keep documentation in sync. + +#### Template schema documentation + +The template schema reference in `site/guide/templates/customize-document-templates.qmd` is auto-generated from the backend JSON Schema. To regenerate: + +```bash +pip install json-schema-for-humans +python scripts/generate_template_schema_docs.py +``` + +**Requirements:** +- The `backend` repo must be cloned at `../backend/` relative to this repo +- Python 3.9+ +- `json-schema-for-humans` package installed + +The script reads from: +- `backend/src/backend/templates/documentation/model_documentation/mdd_template_schema_v5.json` — template schema definition + +Output: `site/guide/templates/_template-schema-generated.html` + +Run this script when the backend template schema changes to keep documentation in sync. + #### Stylesheet organization (IN PROGRESS) The site uses a modular stylesheet architecture to maintain organized and maintainable styles: diff --git a/scripts/generate_template_schema_docs.py b/scripts/generate_template_schema_docs.py new file mode 100644 index 000000000..fa3d9b826 --- /dev/null +++ b/scripts/generate_template_schema_docs.py @@ -0,0 +1,177 @@ +#!/usr/bin/env python3 +# Copyright © 2023-2026 ValidMind Inc. All rights reserved. +# Refer to the LICENSE file in the root of this repository for details. +# SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial +""" +Generate template schema documentation from backend JSON Schema. + +Uses json-schema-for-humans to generate HTML documentation from the +template schema used to validate YAML documentation templates. + +Usage: + pip install json-schema-for-humans + python scripts/generate_template_schema_docs.py + +Requirements: + - Backend repo must be cloned at ../backend/ relative to this repo + - json-schema-for-humans package installed +""" +import subprocess +import sys +from pathlib import Path + +SCRIPT_DIR = Path(__file__).parent +REPO_ROOT = SCRIPT_DIR.parent +BACKEND_ROOT = REPO_ROOT.parent / "backend" + +SCHEMA_FILE = BACKEND_ROOT / "src/backend/templates/documentation/model_documentation/mdd_template_schema_v5.json" +OUTPUT_FILE = REPO_ROOT / "site/guide/templates/_template-schema-generated.html" + +# CSS overrides to fix conflicts with Quarto's Bootstrap +CSS_OVERRIDES = """ + + + +""" + + +def main(): + # Verify schema file exists + if not SCHEMA_FILE.exists(): + print(f"Error: Schema file not found: {SCHEMA_FILE}") + print("Make sure the backend repo is cloned at ../backend/") + sys.exit(1) + + # Check if json-schema-for-humans is installed + try: + subprocess.run( + ["generate-schema-doc", "--help"], + capture_output=True, + check=True + ) + except FileNotFoundError: + print("Error: json-schema-for-humans not installed") + print("Install with: pip install json-schema-for-humans") + sys.exit(1) + + # Generate HTML documentation + print(f"Generating schema documentation from {SCHEMA_FILE}...") + + # Create temporary output + temp_output = OUTPUT_FILE.with_suffix(".tmp.html") + + subprocess.run([ + "generate-schema-doc", + "--config", "expand_buttons=true", + str(SCHEMA_FILE), + str(temp_output) + ], check=True) + + # Read generated HTML and inject CSS overrides + with open(temp_output, "r") as f: + html_content = f.read() + + # Insert CSS overrides after the opening tag + if "" in html_content: + html_content = html_content.replace( + "", + f"\n{CSS_OVERRIDES}" + ) + + # Add copyright header as HTML comment at the top + copyright_header = """ +""" + html_content = copyright_header + html_content + + # Also add Quarto styles link for proper rendering + html_content = html_content.replace( + CSS_OVERRIDES, + f'\n{CSS_OVERRIDES}' + ) + + # Write final output + OUTPUT_FILE.parent.mkdir(parents=True, exist_ok=True) + with open(OUTPUT_FILE, "w") as f: + f.write(html_content) + + # Clean up temp file + temp_output.unlink() + + print(f"Generated {OUTPUT_FILE}") + + +if __name__ == "__main__": + main() diff --git a/site/guide/templates/_template-schema-generated.html b/site/guide/templates/_template-schema-generated.html new file mode 100644 index 000000000..51b76dd1c --- /dev/null +++ b/site/guide/templates/_template-schema-generated.html @@ -0,0 +1,1477 @@ + + + + + + + + + + + + + + + + + + + + + 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 + + + + start_index
Type: integer
+

Starting index for the template.

+ + + + + + + +
+
+
+
+
+
+
+

+ +

+
+ +
+
+ +
root + + + + sections
Type: array
+

Documentation sections of the template.

+ + + + + + + No Additional Items

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 on a given project

+ + + + + + + +
+
+
+
+
+
+
+

+ +

+
+ +
+
+ +
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.

+ + + + + + + No Additional Items

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.

+ + + + + + + No Additional Items

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: "text"
+
+

Must be one of:

+
  • "text"
  • "metadata_text"
  • "dynamic"
  • "metric"
  • "test"
  • "guideline"
  • "assessment_summary"
  • "unit_metric"
+
+ + + + + +
+
Examples:
+
"text"
+
+
"test"
+
+
+
+
+
+
+
+
+
+

+ +

+
+ +
+
+ +
root + + + + sections + + + + sections items + + + + contents + + + + contents items + + + + content_id

+

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

+

+ +

+
+ + +
root + + + + sections + + + + sections items + + + + contents + + + + contents items + + + + content_id + + + + oneOf + + + + item 0
Type: string
+ + + + + + +
+
Example:
+
"sample_text"
+
+
+
+ + +
root + + + + sections + + + + sections items + + + + contents + + + + contents items + + + + content_id + + + + oneOf + + + + item 1
Type: array of string
+ + + + + + + No Additional Items

Each item of this array must be:

+
+
+ + +
root + + + + sections + + + + sections items + + + + contents + + + + contents items + + + + content_id + + + + oneOf + + + + item 1 + + + + item 1 items
Type: string
+ + + + + + + +
+

+
Example:
+
[
+    "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 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.

+ + + + + + + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ + + \ No newline at end of file diff --git a/site/guide/templates/customize-document-templates.qmd b/site/guide/templates/customize-document-templates.qmd index 9e3da18fd..decce062d 100644 --- a/site/guide/templates/customize-document-templates.qmd +++ b/site/guide/templates/customize-document-templates.qmd @@ -62,103 +62,15 @@ Once saved, your new template version becomes available for use. #### Template schema -::: {.column-page-inset-right} + -```{=html} - Schema Docs +::: {.column-page-inset-right} - - - - - - -
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, tests, 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 test content blocks.
-``` +{{< include _template-schema-generated.html >}} :::