notebook / code samples: Auto-updating sidebar script

[validbeck]

Pull Request Description

What and why?

sc-5338

The code samples sidebar in the "ValidMind Library" portal had improper capitalisation of the NLP & LLM directory:

• We wanted to fix that without renaming the directory (which would break links) or manually listing each code_samples subdirectory in the sidebar. Accomplished by adding site/scripts/update_code_samples_sidebar.py which reads subdirectories of notebooks/code_samples/, sorts them alphabetically, and rewrites the “Code samples” links in developer/_sidebar.yaml including adding the proper capitalisation for NLP & LLM.
• After switching to explicit sidebar entries per subdirectory, the section headers did not expand to show the notebooks, so we needed a format that produces expandable sections. The Python script writes section: (not text:) so Quarto renders them as expandable accordion sections.
• Updated site/Makefile: make notebooks now runs the new Python script above after copying notebooks and before zipping, so the sidebar stays in sync with the current code_samples directories whenever make notebooks is run.

documentation/site/Makefile

Line 330 in e8ed26a

@python scripts/update_code_samples_sidebar.py

BEFORE	AFTER
Link	Link

How to test

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

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

mkdir -p _source/validmind-library/notebooks/code_samples/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/code_samples/test_directory/test.ipynb","w").write(json.dumps(n, indent=1))'

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

• There is a new sidebar entry for the test directory (Section: "Test Directory" with contents: "notebooks/code_samples/test_directory/**").
• The new entry is in alphabetical order with the other code sample sections.
• The “NLP and LLM” section still uses that exact title (capitalization unchanged).

What needs special review?

n/a

Dependencies, breaking changes, and deployment notes

n/a

Release notes

n/a

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

No issues found. Checked for bugs and CLAUDE.md compliance.

---

[nrichers]

This looks like a nice fix for an existing issue but I do have one aesthetic comment: we use sentence-style caps in your navigation and your code applies title-style caps. It might be good to update the script to match our convention.

(Approving this as we agreed that aesthetic/style differences should not prevent a PR from being approved.)

[validbeck]

This looks like a nice fix for an existing issue but I do have one aesthetic comment: we use sentence-style caps in your navigation and your code applies title-style caps. It might be good to update the script to match our convention.

(Approving this as we agreed that aesthetic/style differences should not prevent a PR from being approved.)

Arguably, things outlined in our style guide lean towards the technical accuracy bucket, and it would bother me if I saw something and it didn't align, so I think this is fair. Updated in 9513a1a.

[github-actions]

PR Summary

This PR introduces an enhancement to the project’s sidebar configuration. The changes can be summarized as follows:

1. The Makefile has been updated to invoke a new Python script (update_code_samples_sidebar.py) during the build process, ensuring that the sidebar configuration is kept in sync with the code samples directories.

2. The developer/_sidebar.yaml file has been modified to replace a single wildcard entry for code samples with an explicit list of subdirectories. Each subdirectory (e.g., Agents, Capital markets, Code explainer, Credit risk, Custom tests, Model validation, NLP and LLM, Ongoing monitoring, Regression, Time series) is now listed individually with its respective path pattern.

3. The newly added script, update_code_samples_sidebar.py, dynamically scans the notebooks/code_samples directory, sorts the subdirectories alphabetically, and generates the corresponding YAML structure. Special logic is included to properly format specific subdirectory names (e.g., converting 'nlp_and_llm' to 'NLP and LLM'). This script is built to be executed from either the site/ directory or the repository root and performs validations on the existence of required directories and files.

Overall, these changes provide a more robust and maintainable approach to managing the sidebar entries related to code samples, ensuring that any additions or modifications in the code samples directories are accurately reflected in the sidebar configuration.

Test Suggestions

• Run the update_code_samples_sidebar.py script in a controlled environment with a known set of subdirectories to verify that the generated YAML structure matches the expected output.
• Test the Makefile target that invokes the script to ensure it correctly updates the _sidebar.yaml file without errors.
• Simulate scenarios where the notebooks/code_samples directory is missing or empty to confirm that the script correctly handles error conditions.
• Check the sidebar rendering in the generated site to verify that all code samples sections are displayed as expected, particularly the special case for 'nlp_and_llm'.

[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: b9e47cb

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.43	1.00	0.82
/get-started/get-started.html	0.85	0.69	1.00	0.73
/guide/guides.html	0.85	0.69	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

[github-actions]

Validate docs site

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