Skip to content

Nrichers/sc 15354/workflows fix notebook execution workflows#1263

Open
nrichers wants to merge 2 commits intomainfrom
nrichers/sc-15354/workflows-fix-notebook-execution-workflows
Open

Nrichers/sc 15354/workflows fix notebook execution workflows#1263
nrichers wants to merge 2 commits intomainfrom
nrichers/sc-15354/workflows-fix-notebook-execution-workflows

Conversation

@nrichers
Copy link
Copy Markdown
Collaborator

@nrichers nrichers commented Apr 1, 2026 •
edited
Loading

Pull Request Description

What and why?

This PR solves the issue whereby notebook execution and LLM Markdown rendering fail when no generated template schema docs are present but are referenced in an {{< include >}} statement.

The solution:

  • Allow check-in of baseline template schema docs by writers — there's always a file to build regardless of where we're building docs
  • Make template schema docs generation during CI workflows fail harder if the docs cannot be generated — a failsafe to ensure we don't silently publish older baseline docs

The alternative solution would have been a comment marker of some kind that gets replaced with a file embed or a mostly blank template schema docs baseline, both with more downsides than the solution in this PR. Happy to talk through this, if necessary.

Changes:

  • .gitignore — Removed _template-schema-generated.qmd from gitignore so baseline docs can be tracked
  • README.md — Minor documentation updates
  • scripts/generate_template_schema_docs.py — Modified with stricter validation to fail CI on generation errors
  • site/Makefile — Changed pip to python -m pip for environment robustness
  • _template-schema-generated.qmd — Added tracked baseline template schema docs
  • templates/customize-document-templates.qmd — Removed comment that is no longer applicable

Fixes sc-15354

How to test

  1. Verify that the stuff that fails in other PRs completes successfully:
  1. Check that the template schema docs continue to be rendered: Customize email templates

What needs special review?

Dependencies, breaking changes, and deployment notes

Release notes

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)

@nrichers nrichers added the internal Not to be externalized in the release notes label Apr 1, 2026
@nrichers nrichers force-pushed the nrichers/sc-15354/workflows-fix-notebook-execution-workflows branch from b9e42ef to 92c71e8 Compare April 1, 2026 02:36
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 1, 2026

PR Summary

This PR introduces improvements to the template schema documentation generation process and updates the integration in the Quarto markdown templates. The key changes include:

  • Removal of outdated file paths and auto-generated files from the Git repository (e.g. removal of the generated schema file from the .gitignore).
  • Updates to the README to clarify that the template schema reference is generated from the backend JSON Schema and is injected into the main template file between marker comments. The user is now instructed to regenerate and commit the output.
  • Modifications in the Python script (generate_template_schema_docs.py) that generates the schema documentation:
    • Renamed variables (e.g., OUTPUT_FILE to TARGET_FILE) for clarity.
    • Introduction of a sanity check on the output size (minimum expected file size) to detect generation failures.
    • Additional validation ensuring the generated HTML contains expected structure (presence of <html and </html> tags) before committing the file.
    • Cleanup of the generated HTML by stripping unwanted tags (like <title> and <h1>) and extra blank lines, then wrapping it in a Quarto raw HTML block.
    • Improved error messaging and temporary file cleanup in case of failure.
  • A minor update to the Makefile command that installs dependencies by using python -m pip instead of invoking pip directly.
  • A cleanup in the customization template file (customize-document-templates.qmd) that removes outdated or commented instructions, relying on the included auto-generated file.

Overall, these changes help improve the reliability and clarity of schema documentation generation as well as streamline its integration with the documentation site.

Test Suggestions

  • Run the schema generation script with a valid backend JSON Schema and verify that the target file is generated with the expected HTML structure and injected content.
  • Test error handling by simulating a generation failure (e.g., by providing an empty or invalid schema file) and confirming that the script exits with an error after cleaning up temporary files.
  • Verify that the generated HTML does not include unnecessary title or h1 tags and that blank lines are appropriately cleaned up.
  • Execute the Makefile target 'template-schema-docs' to ensure that dependency installation and schema generation works seamlessly in a fresh environment.
  • Manually review the injected content in 'customize-document-templates.qmd' to ensure that it properly reflects the updated schema documentation.

@nrichers nrichers requested review from nibalizer and validbeck April 1, 2026 03:16
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 1, 2026

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: 7e4425b

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.69 1.00 0.82
/get-started/get-started.html 0.85 0.71 1.00 0.73
/guide/guides.html 0.81 0.68 1.00 0.82
/index.html 0.93 0.68 1.00 0.82
/releases/all-releases.html 0.86 0.71 1.00 0.73
/support/support.html 0.91 0.69 1.00 0.82
/training/training.html 0.85 0.65 0.96 0.73

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 1, 2026

Validate docs site

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

nrichers
nrichers commented Apr 1, 2026
View reviewed changes
scripts/generate_template_schema_docs.py
TARGET_FILE = REPO_ROOT / "site/guide/templates/_template-schema-generated.qmd"

# Minimum expected file size in bytes (sanity check for valid output)
MIN_OUTPUT_SIZE = 1000
Copy link
Copy Markdown
Collaborator Author

@nrichers nrichers Apr 1, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
MIN_OUTPUT_SIZE = 1000
MIN_OUTPUT_SIZE = 40000

Current outputs are around 62,000 bytes, so allowing for shorter versions in the future should work but we likely don't want to set this too low.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@nibalizer nibalizer nibalizer approved these changes

@validbeck validbeck Awaiting requested review from validbeck

Assignees

No one assigned

Labels

internal Not to be externalized in the release notes

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@nrichers @nibalizer