feat: clean up orphaned MDX files when notebooks are deleted or renamed

[kadolor]

Summary

Fixes a gap in PR #115 where deleted or moved notebooks were not automatically cleaned up from the docs repo.

• Problem: When a notebook is deleted or renamed in wherobots-examples, the corresponding MDX file and images remain in wherobots/docs, creating orphaned content.
• Solution: Add a cleanup step that runs before conversion to detect and remove orphaned MDX files.

Changes

• Add cleanup_orphaned_mdx.py script that:

  • Compares existing MDX files against source notebooks
  • Removes orphaned MDX files (no corresponding notebook)
  • Removes associated images (prefixed with notebook slug)
  • Supports --dry-run for testing

• Update workflow (convert-notebooks.yml):

  • Run cleanup step before conversion
  • Use git add -A to stage deletions
  • Add cleanup script to trigger paths

• Update Makefile:

  • Add make cleanup target
  • make preview and make all now run cleanup before convert

Behavior

Scenario	Before	After
Notebook deleted	Orphaned MDX remains	MDX and images removed
Notebook renamed	Old + new MDX exist	Old MDX removed, new created

Testing

Run locally with make cleanup --dry-run to preview what would be removed (once --dry-run is passed through).

[gitnotebooks]

Review these changes at https://app.gitnotebooks.com/wherobots/wherobots-examples/pull/118

[Copilot]

Pull request overview

This PR adds automated cleanup of orphaned MDX files when notebooks are deleted or renamed in the wherobots-examples repository. Previously, when notebooks were removed or renamed, their corresponding MDX documentation and images remained in the docs repo, creating stale content.

Changes:

• Adds a cleanup script that compares existing MDX files against source notebooks and removes orphans
• Updates the GitHub Actions workflow to run cleanup before conversion and track deleted files in PR descriptions
• Updates the Makefile to include cleanup in local development workflows

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
.github/workflows/scripts/cleanup_orphaned_mdx.py	New script implementing orphaned file detection and removal logic
.github/workflows/convert-notebooks.yml	Adds cleanup step before conversion and includes deletion tracking in PR body
Makefile	Adds cleanup target and integrates it into preview/all workflows

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The exclude_prefix parameter should be Optional[str] since line 30 checks if exclude_prefix which suggests it can be None or empty. Update the type hint to Optional[str] and import Optional from typing.

[Copilot]

Using a hardcoded path in /tmp could cause issues in environments where /tmp has restricted permissions or in concurrent workflow runs. Consider using mktemp to create a unique temporary file or use $RUNNER_TEMP which is a GitHub Actions environment variable for temporary files.

Suggested change

	python wherobots-examples/.github/workflows/scripts/cleanup_orphaned_mdx.py \
	${{ steps.find-dirs.outputs.dirs }} \
	--mdx-dir docs/tutorials/example-notebooks \
	--exclude-prefix Raster_Inference \
	--output-file /tmp/removed-mdx.txt \
	-v
	if [ -f /tmp/removed-mdx.txt ] && [ -s /tmp/removed-mdx.txt ]; then
	echo "has_deletions=true" >> $GITHUB_OUTPUT
	echo "deleted_files<<EOF" >> $GITHUB_OUTPUT
	cat /tmp/removed-mdx.txt | sed 's/^/- /' >> $GITHUB_OUTPUT
	REMOVED_MDX_FILE="$(mktemp "${RUNNER_TEMP:-/tmp}/removed-mdx.XXXXXX")"
	python wherobots-examples/.github/workflows/scripts/cleanup_orphaned_mdx.py \
	${{ steps.find-dirs.outputs.dirs }} \
	--mdx-dir docs/tutorials/example-notebooks \
	--exclude-prefix Raster_Inference \
	--output-file "$REMOVED_MDX_FILE" \
	-v
	if [ -f "$REMOVED_MDX_FILE" ] && [ -s "$REMOVED_MDX_FILE" ]; then
	echo "has_deletions=true" >> $GITHUB_OUTPUT
	echo "deleted_files<<EOF" >> $GITHUB_OUTPUT
	cat "$REMOVED_MDX_FILE" | sed 's/^/- /' >> $GITHUB_OUTPUT

[Copilot]

The shell command will fail if there are no notebooks found (xargs will receive no input). Consider adding find ... -print0 | xargs -0 for better handling of filenames with spaces, and add 2>/dev/null || true to handle the case when no notebooks exist gracefully.

Suggested change

	NOTEBOOK_DIRS = $(shell find . -name "*.ipynb" -type f | xargs -I {} dirname {} | sort -u | grep -v ".ipynb_checkpoints")
	NOTEBOOK_DIRS = $(shell find . -name "*.ipynb" -type f -print0 2>/dev/null | xargs -0 -I {} dirname "{}" 2>/dev/null | sort -u | grep -v ".ipynb_checkpoints" || true)

[kadolor]

Closing in favor of #129