Add auto-generated template schema documentation

[nrichers]

What and why?

Generate template schema documentation from backend JSON schema using json-schema-for-humans, replacing outdated hardcoded HTML (last generated June 2023) with script-based generation.

Files changed:

• scripts/generate_template_schema_docs.py — new generation script
• site/guide/templates/customize-document-templates.qmd — includes generated file via {{< include >}}
• site/guide/templates/_template-schema-generated.qmd — generated output, wrapped in {=html} block as before
• site/assets/styles/template-schema.css — ValidMind branding overrides
• site/guide/templates/schema_doc.css — base schema styles from json-schema-for-humans
• site/guide/templates/schema_doc.min.js — collapse/expand functionality
• site/Makefile — new template-schema-docs target
• .github/workflows/validate-docs-site.yaml — CI step for schema generation
• .github/workflows/deploy-docs-staging.yaml — CI step for schema generation
• .github/workflows/deploy-docs-prod.yaml — CI step for schema generation
• .gitignore — added _template-schema-generated.qmd pattern
• README.md — added "Template schema documentation" section with regeneration instructions

Differences

Content aside, the old and new versions show a couple of minor fixes:

1. Heading level fix — Uses the correct h3 ### Template schema to appear in the page ToC
2. Style cleanup — Removed distracting pink surround and "Generated by" footer via CSS overrides

Schema property differences

New property added:

• start_index — not present in old schema

content_type enum values expanded:

Old values	New values
metadata_text	text
dynamic	metadata_text
metric	dynamic
test	metric
	test
	guideline
	assessment_summary
	unit_metric

New content types added: text, guideline, assessment_summary, unit_metric

How to test

Try the preview: Template schema

Before	After

Local testing:

gh pr checkout 1166
cd site
make get-source 
make template-schema-docs

Output:

❯ make template-schema-docs

Generating template schema documentation ...
Generating schema documentation from _source/backend/src/backend/templates/documentation/model_documentation/mdd_template_schema_v5.json
== Generating _template-schema-generated.tmp.html ==
== Generated _template-schema-generated.tmp.html in 0:00:00.059605 ==
Generated /Users/nrichers/GitHub/validmind/documentation/site/../site/guide/templates/_template-schema-generated.qmd

The output file is in the .gitignore as we don't need it to be committed to the repo, same approach as for our Python API docs that are generated on the fly.

What needs special review?

N/A

Dependencies, breaking changes, and deployment notes

Depends on https://github.com/validmind/backend/pull/2845

Release notes

N/A — internal change

Checklist

• What and why
• Screenshots or videos (Frontend)
• How to test
• What needs special review
• Dependencies, breaking changes, and deployment notes
• Labels applied
• PR linked to Shortcut
• Unit tests added (Backend)
• Tested locally
• Documentation updated (if required)
• Environment variable additions/changes documented (if required)

Closes sc-6164

[github-actions]

Pull requests must include at least one of the required labels: internal, highlight, enhancement, bug, deprecation, documentation. Except for internal, pull requests must also include a description in the release notes section.

[github-actions]

Pull requests must include at least one of the required labels: internal, highlight, enhancement, bug, deprecation, documentation. Except for internal, pull requests must also include a description in the release notes section.

[validbeck]

When I try to pull this down to preview to see what already exists, I get the following very strange error:

quarto preview --profile development
error: Uncaught (in promise) Error: Include directive failed.
  in file /Users/beckchan/Documents/GitHub/validmind/documentation/site/guide/templates/customize-document-templates.qmd, 
  could not find file /Users/beckchan/Documents/GitHub/validmind/documentation/site/guide/templates/_template-schema-generated.qmd.
      throw new Error(errMsg.join("\n"));
            ^
    at retrieveInclude (file:///Applications/quarto/bin/quarto.js:70432:13)
    at standaloneInclude (file:///Applications/quarto/bin/quarto.js:70465:9)
    at processMarkdownIncludes (file:///Applications/quarto/bin/quarto.js:70703:30)
    at eventLoopTick (ext:core/01_core.js:178:7)
    at async expandIncludes (file:///Applications/quarto/bin/quarto.js:70734:3)
    at async projectResolveFullMarkdownForFile (file:///Applications/quarto/bin/quarto.js:78006:21)
    at async fileExecutionEngine (file:///Applications/quarto/bin/quarto.js:79894:22)
    at async addFile (file:///Applications/quarto/bin/quarto.js:120178:20)

However, when I do call make template-schema-docs it seems to resolve itself (likely because you included it in the .gitignore... so maybe we need some prereq note in the README to ensure that new writers pull this in?).

Otherwise, it looks good from a docs perspective but I do not know how accurate the actual content is — I also don't seem to see the "this is the only content in this class" or something note in any of the modules I clicked on that you showed me yesterday so I don't know if I'm looking in the wrong places or if that got removed? 🤔

[nrichers]

error: Uncaught (in promise) Error: Include directive failed.
  in file /Users/beckchan/Documents/GitHub/validmind/documentation/site/guide/templates/customize-document-templates.qmd, 
  could not find file /Users/beckchan/Documents/GitHub/validmind/documentation/site/guide/templates/_template-schema-generated.qmd.
      throw new Error(errMsg.join("\n"));

This is expected and a standard error when Quarto can't find a file. Really no different than missing installation, release-notes, and some library files (e.g. Python API) unless you first run make get-source. I'll see what I can add to the README.md but it will be a general recommendation.

EDIT: Addressed in 28a6f30 (and removed some stale R info for breaking changes).

[nrichers]

I also don't seem to see the "this is the only content in this class" or something note in any of the modules I clicked on that you showed me yesterday so I don't know if I'm looking in the wrong places or if that got removed? 🤔

Still there, here's an example:

[validbeck]

I also don't seem to see the "this is the only content in this class" or something note in any of the modules I clicked on that you showed me yesterday so I don't know if I'm looking in the wrong places or if that got removed?

Aha, you made it pink. It used to just be text, so I think maybe I was looking for that. Or hallucinated it as text...

[cachafla]

Relevant: https://validmind.slack.com/archives/C04LL15THJA/p1774290125535089

[github-actions]

Lighthouse check results

⚠️ WARN: Average accessibility score is 0.87 (required: >0.9) — Check the workflow run

Show Lighthouse scores

Folder depth level checked: 0

Commit SHA: b69f78d

Modify the workflow to check a different depth:

• 0: Top-level navigation only — /index.html, /guide/guides.html, ...
• 1: All first-level subdirectories — /guide/.html, /developer/.html, ...
• 2: All second-level subdirectories — /guide/attestation/*.html, ...

Page	Accessibility	Performance	Best Practices	SEO
/developer/validmind-library.html	0.85	0.67	1.00	0.82
/get-started/get-started.html	0.85	0.72	1.00	0.73
/guide/guides.html	0.81	0.69	1.00	0.82
/index.html	0.93	0.68	1.00	0.82
/releases/all-releases.html	0.86	0.70	1.00	0.73
/support/support.html	0.91	0.67	1.00	0.82
/training/training.html	0.85	0.69	0.96	0.73

[github-actions]

PR Summary

This PR enhances the documentation deployment workflows by adding new steps that check out the backend repository (using sparse checkout) and auto-generate template schema documentation. The following are the main changes:

1. In several GitHub Actions workflows (deploy-docs-prod.yaml, deploy-docs-staging.yaml, and validate-docs-site.yaml), a new step is added to checkout the backend repository from a specific repository path (src/backend/templates/documentation/model_documentation) using a token and sparse checkout options. This ensures that only the required backend schema files are fetched.

2. A new step named "Generate template schema docs" is introduced in the workflows. This step installs the dependency json-schema-for-humans and runs a Python script (scripts/generate_template_schema_docs.py) that generates HTML documentation of the backend JSON schema, then wraps it in a Quarto raw HTML block to produce a QMD file (specifically, site/guide/templates/_template-schema-generated.qmd).

3. The README.md has been updated with instructions on how to clone the repos and regenerate the template schema docs locally using Make commands. The Makefile in the site directory now includes a new target (template-schema-docs) that automates this process.

4. Additionally, the .gitignore is updated to ignore the auto-generated template schema documentation file and new stylesheet and script files have been added/updated to support the presentation of the schema docs.

Overall, these changes improve the automation for keeping documentation in sync with backend changes and streamline local development and CI/CD processes for the docs site.

Test Suggestions

• Run the new Makefile targets (e.g., 'make get-source' and 'make template-schema-docs') locally and verify that the _template-schema-generated.qmd file is generated correctly with the updated schema content.
• Trigger both staging and production workflows to ensure the backend repository is correctly checked out using sparse checkout and the template documentation generation step runs without errors.
• Check the rendered docs site to verify that the generated template schema documentation is correctly included using the new include directive ({{< include _template-schema-generated.qmd >}}).
• Verify that the cleanup steps properly remove the backend source directory from the site after documentation generation to avoid unintended file exposure.

[github-actions]

Validate docs site

✓ INFO: A live preview of the docs site is available — Open the preview