docs: Reorganize ValidMind Library "portal" around sorted Jupyter Notebooks

[validbeck]

Pull Request Description

What and why?

sc-14582

This PR pulls in the updated notebook structure from validmind/validmind-library#475 and revamps the ValidMind Library "portal" to feature our more organized notebooks:

OLD PORTAL	NEW PORTAL
old-portal.mov	new-portal.mov

1. Sidebar restructured (site/developer/_sidebar.yaml)

The developer sidebar received a significant reorganization:

• "Model Testing" section renamed to "How-To" with two main entries:
  • "Run tests & test suites" — links to the new testing-overview.qmd with nested sections for Explore tests, Run tests (with sub-sections Configuring tests and Documentation tests), and Custom tests.
  • "Use library features" — links to the new feature-overview.qmd with auto-populated sections for Data and datasets, Metrics, and Scoring.
• Tutorials grouped into collapsible "Model development" and "Model validation" sub-sections under an "End-to-End Tutorials" heading (previously flat lists).
• "Code samples" section now points to use_cases/ paths with **/*.ipynb globs (instead of the old code_samples/ + ** catch-all).
• "Test descriptions" moved from under "Model Testing" into the "Reference" section where it fits better conceptually.

2. Build scripts replaced and expanded

The old single script site/scripts/update_code_samples_sidebar.py was deleted and replaced by two scripts in site/scripts/developer-sidebar/:

• update_use_cases.py — Auto-discovers use_cases/ subdirectories and updates both the sidebar YAML and samples-jupyter-notebooks.qmd with per-category listing tiles (panel tabset).
• update_how_tos.py — Auto-discovers how_to/ subdirectories and updates both the sidebar YAML and the new feature-overview.qmd with per-topic listing tiles.
• site/Makefile — Minor adjustments to accommodate the new script paths and calling the new scripts.

Both Python scripts generate Quarto listing blocks with grid layouts and panel tabsets, borrowing the tabbed tile pattern already used on the "Test descriptions" page. They update both the sidebar and their respective landing pages in a single run.

3. New and updated landing pages

• developer/how-to/testing-overview.qmd — New page (replacing the old developer/model-testing/testing-overview.qmd) serving as the landing for "Run tests & test suites" under the How-To section.
• developer/how-to/feature-overview.qmd — New landing page for "Use library features" with auto-populated notebook listing tiles grouped by topic.
• developer/samples-jupyter-notebooks.qmd — Rewritten to use panel tabsets auto-populated by the update_use_cases.py script.
• developer/validmind-library.qmd — Updated to reflect the new structure and section names.
• developer/test-descriptions.qmd — Moved up from developer/model-testing/ to developer/ and adjusted.
• developer/model-testing/test-sandbox.qmd moved to developer/how-to/test-sandbox.qmd to live alongside the new How-To pages.

4. Comprehensive broken link fixes

Links referencing the old code_samples/ paths were updated across ~30 files spanning:

• Release notes (2023 and 2024 vintage)
• FAQ pages
• Guide pages (monitoring, model documentation)
• Training materials
• About/use case pages

How to test

Review the live previews

• ValidMind Library
  • How to run tests and test suites
  • How to use ValidMind Library features
  • Code samples

Test the developer-sidebar scripts

1. Pull down this PR: gh pr checkout 1168
2. From the repo root, go into the site directory: cd site
3. Create a new use_cases directory and add a test notebook:

• Create directory: _source/validmind-library/notebooks/use_cases/test_directory
• In that directory, create test.ipynb

mkdir -p _source/validmind-library/notebooks/use_cases/test_directory
python3 -c 'import json; n={"nbformat":4,"nbformat_minor":4,"metadata":{},"cells":[{"cell_type":"markdown","metadata":{},"source":["test"]}]}; open("_source/validmind-library/notebooks/use_cases/test_directory/test.ipynb","w").write(json.dumps(n, indent=1))'

4. Create a new how_to directory and add a test notebook:

• Create directory: _source/validmind-library/notebooks/how_to/test_directory
• In that directory, create test.ipynb

mkdir -p _source/validmind-library/notebooks/how_to/test_directory
python3 -c 'import json; n={"nbformat":4,"nbformat_minor":4,"metadata":{},"cells":[{"cell_type":"markdown","metadata":{},"source":["test"]}]}; open("_source/validmind-library/notebooks/how_to/test_directory/test.ipynb","w").write(json.dumps(n, indent=1))'

5. From the site directory, run: make notebooks
6. Open site/developer/_sidebar.yaml and confirm:

• There is a new sidebar entry for the test directories under "Use library features" and "Code samples"
• There are new listing categories for the new test directories under the landing pages:
  • site/developer/how-to/feature-overview.qmd
  • site/developer/samples-jupyter-notebooks.qmd

What needs special review?

n/a

Dependencies, breaking changes, and deployment notes

Pulls from the notebook reshuffle in validmind/validmind-library#475.

Release notes

We've restructured our {{< var validmind.developer >}} guides to better familiarize users with the capabilities of the {{< var vm.developer >}}. Detailed information on how to use the {{< var vm.developer >}}'s rich features — such as how to run tests, as well examples on how to apply {{< var vm.product >}} to your custom use case can all be found under the new and improved:

{{< var validmind.developer >}}{.button}

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)

[claude]

Code review

Found 2 issues that need attention:

Issue 1: Incorrect relative paths in supported-models.qmd

File: site/developer/supported-models.qmd (lines 17-19)

The listing contents paths on lines 17 and 19 use incorrect ../ prefixes that resolve to non-existent files:

• Line 17: ../how-to/testing-overview.qmd → resolves to site/how-to/testing-overview.qmd ❌ (does not exist)
• Line 19: ../samples-jupyter-notebooks.qmd → resolves to site/samples-jupyter-notebooks.qmd ❌ (does not exist)

Fix: Remove the ../ prefix so paths resolve correctly to site/developer/:

contents:
- how-to/testing-overview.qmd
- test-descriptions.qmd
- samples-jupyter-notebooks.qmd

See site/developer/validmind-library.qmd which correctly uses this pattern.

---

Issue 2: Non-recursive glob missing notebooks in feature-overview.qmd

File: site/developer/how-to/feature-overview.qmd (line 24)

The glob pattern for "Data and datasets" uses a non-recursive glob (*.ipynb) which only matches notebooks in the root directory, missing 2 notebooks in the dataset_inputs/ subdirectory:

• configure_dataset_features.ipynb
• load_datasets_predictions.ipynb

Current:

contents: "../../notebooks/how_to/data_and_datasets/*.ipynb"

Fix: Use a recursive glob to match all notebooks:

contents: "../../notebooks/how_to/data_and_datasets/**/*.ipynb"

This matches the pattern used in _sidebar.yaml line 70 for consistency.

[validbeck]

Code review

Found 2 issues that need attention:

Issue 1: Incorrect relative paths in supported-models.qmd

File: site/developer/supported-models.qmd (lines 17-19)

The listing contents paths on lines 17 and 19 use incorrect ../ prefixes that resolve to non-existent files:

• Line 17: ../how-to/testing-overview.qmd → resolves to site/how-to/testing-overview.qmd ❌ (does not exist)
• Line 19: ../samples-jupyter-notebooks.qmd → resolves to site/samples-jupyter-notebooks.qmd ❌ (does not exist)

Fix: Remove the ../ prefix so paths resolve correctly to site/developer/:

contents:
- how-to/testing-overview.qmd
- test-descriptions.qmd
- samples-jupyter-notebooks.qmd

See site/developer/validmind-library.qmd which correctly uses this pattern.

Issue 2: Non-recursive glob missing notebooks in feature-overview.qmd

File: site/developer/how-to/feature-overview.qmd (line 24)

The glob pattern for "Data and datasets" uses a non-recursive glob (*.ipynb) which only matches notebooks in the root directory, missing 2 notebooks in the dataset_inputs/ subdirectory:

• configure_dataset_features.ipynb
• load_datasets_predictions.ipynb

Current:

contents: "../../notebooks/how_to/data_and_datasets/*.ipynb"

Fix: Use a recursive glob to match all notebooks:

contents: "../../notebooks/how_to/data_and_datasets/**/*.ipynb"

This matches the pattern used in _sidebar.yaml line 70 for consistency.

Fixed in d280ef1 and ddc70d0 — super cool bot!

[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: 29492e6

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.55	1.00	0.82
/get-started/get-started.html	0.85	0.68	1.00	0.73
/guide/guides.html	0.85	0.68	1.00	0.82
/index.html	0.93	0.66	1.00	0.82
/releases/all-releases.html	0.86	0.68	1.00	0.73
/support/support.html	0.91	0.66	1.00	0.82
/training/training.html	0.85	0.70	0.96	0.73

[nrichers]

This is a great PR! Wow. 👏 I especially love the clean structure of the "How to run tests and test suites" section.

Just a few minor comments I found while comparing the old and new side-by-side.

[nrichers]

@validbeck the validate CI failure will go away after https://github.com/validmind/installation/pull/189 is merged, FYI.

[github-actions]

Validate docs site

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

[github-actions]

Execute training notebooks for PRs

✓ INFO: Live previews are available —

• Open model development series
• Open model validation series