ci: Speedup Notebook execution

[FBumann]

Description

Brief description of the changes in this PR.

Type of Change

• Bug fix
• New feature
• Documentation update
• Code refactoring

Related Issues

Closes #(issue number)

Testing

• I have tested my changes
• Existing tests still pass

Checklist

• My code follows the project style
• I have updated documentation if needed
• I have added tests for new functionality (if applicable)

Summary by CodeRabbit

• Chores
  • Optimized documentation build workflow with caching and parallel execution for faster deployment cycles.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

📝 Walkthrough

Walkthrough

The documentation build workflow now implements caching for executed notebooks and parallel execution when cache misses occur. The notebook execution flag in the mkdocs configuration is delegated to an environment variable, allowing the CI pipeline to control execution timing rather than always executing.

Changes

Cohort / File(s)	Summary
GitHub Actions workflow optimization .github/workflows/docs.yaml	Adds notebook execution caching using a hash computed from notebook and source files; conditionally executes notebooks in parallel (4 concurrent) only on cache miss; injects MKDOCS_JUPYTER_EXECUTE environment variable in Build and Deploy steps. Changes applied to both build and deploy job sequences.
Configuration environment variable delegation mkdocs.yml	Replaces hardcoded notebook execution flag with environment variable reference: !ENV [MKDOCS_JUPYTER_EXECUTE, true]. Preserves default behavior (true) while allowing CI override.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 Swift whiskers twitch with glee,
Cached notebooks race in harmony!
Four at once, no time to waste,
Building docs at blistering pace,
Environment flags guide the way—
Docs redeploy faster each day! ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is entirely composed of unfilled template placeholders with no actual content describing the changes; only checklist items are marked without substance.	Replace template placeholders with meaningful descriptions of the actual changes, specify the type of change (e.g., 'New feature'), list related issue numbers, and describe testing performed.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title 'ci: Speedup Notebook execution' directly and accurately reflects the main changes in the pull request, which focus on optimizing notebook execution in CI through caching and parallelization.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[FBumann]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

.github/workflows/docs.yaml (2)

74-79: Consider explicitly aligning notebook execution with mkdocs-jupyter configuration.

The parallel execution finds all .ipynb files recursively, which may include notebooks that shouldn't be processed. While the current setup appears safe based on the nav structure, explicitly aligning with mkdocs-jupyter's ignore patterns would make the behavior more maintainable and prevent accidental execution of draft or test notebooks.

🔎 Optional improvement to align with ignore patterns

       - name: Execute notebooks in parallel
         if: steps.notebook-cache.outputs.cache-hit != 'true'
         run: |
           # Execute all notebooks in parallel (4 at a time)
-          find docs/notebooks -name '*.ipynb' -print0 | \
+          find docs/notebooks -name '*.ipynb' ! -path '*/data/*' -print0 | \
             xargs -0 -P 4 -I {} jupyter execute --inplace {}

This explicitly excludes the data/ subdirectory, matching the mkdocs-jupyter ignore pattern.

---

121-148: Notebook preparation is correctly duplicated for job isolation.

The deploy job independently implements the same caching and parallel execution logic as the build job. While this creates some duplication, it ensures the deploy job can run independently and maintains workflow clarity.

If you anticipate further changes to the notebook execution logic, consider extracting it into a composite action to reduce maintenance overhead.

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 93e7152 and fd8ad23.

📒 Files selected for processing (2)

• .github/workflows/docs.yaml
• mkdocs.yml

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)

• GitHub Check: test (3.12)
• GitHub Check: test (3.11)
• GitHub Check: test (3.13)
• GitHub Check: test (3.14)
• GitHub Check: Build documentation

🔇 Additional comments (3)

mkdocs.yml (1)

233-233: Good pattern for CI-controlled execution.

The environment variable delegation with a sensible default (true) preserves local development behavior while allowing CI to optimize by pre-executing notebooks in parallel and then skipping re-execution during the build step.

.github/workflows/docs.yaml (2)

67-72: Caching strategy is well-designed.

The cache path correctly targets the notebooks directory, and the key appropriately includes both notebook content and source code changes, ensuring cache invalidation when either changes.

---

81-84: Correct integration with pre-execution strategy.

Setting MKDOCS_JUPYTER_EXECUTE="false" properly prevents mkdocs from re-executing the notebooks that were already executed in parallel, optimizing the build time.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Sort files before hashing to ensure stable cache keys.

The cache key computation concatenates file contents without sorting, which means filesystem iteration order affects the hash. This can lead to different cache keys for identical content across runs, reducing cache effectiveness.

🔎 Proposed fix to stabilize cache keys

       - name: Get notebook cache key
         id: notebook-cache-key
         run: |
           # Hash notebooks + flixopt source code
-          HASH=$(find docs/notebooks -name '*.ipynb' -exec cat {} \; | cat - <(find flixopt -name '*.py' -exec cat {} \;) | sha256sum | cut -d' ' -f1)
+          HASH=$(find docs/notebooks -name '*.ipynb' | sort | xargs cat | cat - <(find flixopt -name '*.py' | sort | xargs cat) | sha256sum | cut -d' ' -f1)
           echo "hash=$HASH" >> $GITHUB_OUTPUT

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	- name: Get notebook cache key
	id: notebook-cache-key
	run: |
	# Hash notebooks + flixopt source code
	HASH=$(find docs/notebooks -name '*.ipynb' -exec cat {} \; | cat - <(find flixopt -name '*.py' -exec cat {} \;) | sha256sum | cut -d' ' -f1)
	echo "hash=$HASH" >> $GITHUB_OUTPUT
	- name: Get notebook cache key
	id: notebook-cache-key
	run: |
	# Hash notebooks + flixopt source code
	HASH=$(find docs/notebooks -name '*.ipynb' | sort | xargs cat | cat - <(find flixopt -name '*.py' | sort | xargs cat) | sha256sum | cut -d' ' -f1)
	echo "hash=$HASH" >> $GITHUB_OUTPUT

🤖 Prompt for AI Agents

.github/workflows/docs.yaml around lines 60 to 65: the hash is computed by
concatenating notebook and flixopt file contents in filesystem order, which is
non-deterministic; change the pipeline to list files first, sort the filenames
deterministically (e.g., using find to print paths and sort), then cat the files
in that sorted order (use a null-safe approach if filenames may contain special
characters) so the same set of files always yields the same hash.