new workflow action to prevent misc categorization of new notebooks by kadolor · Pull Request #125 · wherobots/wherobots-examples

kadolor · 2026-02-06T23:42:22Z

No description provided.

…dated, and navigation is correctly mapped

gitnotebooks · 2026-02-06T23:42:26Z

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

…n permissions Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

Copilot

Pull request overview

Adds enforcement and clearer guidance to ensure new/modified notebooks are correctly categorized in docs navigation, preventing accidental fallback into an “Other” bucket.

Changes:

Documented the notebook→MDX publishing workflow and instructions for updating navigation mappings.
Switched docs navigation from prefix-based categorization to an explicit filename→category mapping.
Added a PR workflow to fail when notebooks change without updating the navigation config; normalized MDX output filenames to lowercase.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
README.md	Documents docs publishing pipeline and required mapping update steps for new notebooks.
Makefile	Makes `convert` depend on `clean` to ensure a fresh conversion output.
.github/workflows/scripts/update_docs_navigation.py	Replaces pattern matching with explicit filename→category mapping and simplifies categorization.
.github/workflows/scripts/notebook_to_mdx.py	Normalizes generated MDX filenames to lowercase to align with mapping expectations.
.github/workflows/check-notebooks.yml	Adds CI guardrails ensuring notebook changes accompany navigation config updates.

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

Copilot · 2026-02-06T23:45:08Z

+          BASE_BRANCH: ${{ github.base_ref }}
+        run: |
+          echo "Comparing HEAD against origin/$BASE_BRANCH..."
+
+          # Get list of changed files between the PR branch and the base branch
+          CHANGED_FILES=$(git diff --name-only origin/$BASE_BRANCH HEAD)


origin/$BASE_BRANCH may not exist in the runner clone (even with fetch-depth: 0), which can cause git diff to fail or return incomplete results. Prefer using the PR-provided SHAs (base SHA vs head SHA) or explicitly git fetch origin $BASE_BRANCH before diffing.

Suggested change

BASE_BRANCH: ${{ github.base_ref }}

run: |

echo "Comparing HEAD against origin/$BASE_BRANCH..."

# Get list of changed files between the PR branch and the base branch

CHANGED_FILES=$(git diff --name-only origin/$BASE_BRANCH HEAD)

BASE_SHA: ${{ github.event.pull_request.base.sha }}

HEAD_SHA: ${{ github.event.pull_request.head.sha }}

run: |

echo "Comparing changes between BASE_SHA=$BASE_SHA and HEAD_SHA=$HEAD_SHA..."

# Get list of changed files between the PR base commit and the PR head commit

CHANGED_FILES=$(git diff --name-only "$BASE_SHA" "$HEAD_SHA")

Copilot · 2026-02-06T23:45:09Z

+          # Extract filenames without extensions for comparison
+          HAS_IPYNB=$(echo "$CHANGED_FILES" | grep '\.ipynb$' | sed 's/\.ipynb$//' || true)


The mapping keys in update_docs_navigation.py are documented/implemented as basename, underscore→hyphen, lowercase. This check currently compares the path without extension (e.g., some/dir/My_New.ipynb → some/dir/My_New) against the config file, which will frequently fail even when the mapping exists. Also, grep -q treats the input as a regex; notebook names containing regex metacharacters (e.g., *) can produce incorrect matches. Normalize notebook names to the same canonical form used in conversion/mapping (strip directories, replace _ with -, lowercase) and use fixed-string matching (grep -Fq) or parse the dict keys more robustly.

Copilot · 2026-02-06T23:45:09Z

+            while IFS= read -r notebook; do
+              if ! grep -q "$notebook" <<< "$CONFIG_CONTENT"; then
+                MISSING_MAPPING="$MISSING_MAPPING\n$notebook"
+              fi
+            done <<< "$HAS_IPYNB"


The mapping keys in update_docs_navigation.py are documented/implemented as basename, underscore→hyphen, lowercase. This check currently compares the path without extension (e.g., some/dir/My_New.ipynb → some/dir/My_New) against the config file, which will frequently fail even when the mapping exists. Also, grep -q treats the input as a regex; notebook names containing regex metacharacters (e.g., *) can produce incorrect matches. Normalize notebook names to the same canonical form used in conversion/mapping (strip directories, replace _ with -, lowercase) and use fixed-string matching (grep -Fq) or parse the dict keys more robustly.

Copilot · 2026-02-06T23:45:09Z

+
+          # If there are notebooks without mappings, fail the build
+          if [[ -n "$MISSING_MAPPING" ]]; then
+            echo "::error::⛔ FAILURE: The following notebooks are missing mappings in $CONFIG_FILE_PATH:$MISSING_MAPPING"


GitHub Actions ::error:: annotations don’t reliably render embedded \\n line breaks inside a single message, so $MISSING_MAPPING may appear as a literal \\n or as a hard-to-read single line. Consider emitting one ::error:: per missing notebook (or printing the list as normal log lines and keeping the annotation concise).

Suggested change

echo "::error::⛔ FAILURE: The following notebooks are missing mappings in $CONFIG_FILE_PATH:$MISSING_MAPPING"

echo "⛔ FAILURE: The following notebooks are missing mappings in $CONFIG_FILE_PATH:"

# Interpret the '\n' escape sequences in MISSING_MAPPING as actual newlines

printf '%b\n' "$MISSING_MAPPING"

echo "::error::⛔ FAILURE: One or more notebooks are missing mappings in $CONFIG_FILE_PATH. See the list above for details."

Copilot · 2026-02-06T23:45:09Z

@@ -46,13 +64,7 @@

 def get_category(filename: str) -> str:
    """Determine category for a notebook based on filename."""


notebook_to_mdx.py now lowercases output filenames, and the mapping keys are lowercase; however, get_category assumes the caller always passes a lowercased stem. If any upstream caller passes a non-normalized stem (e.g., pre-existing MDX files with mixed case, or different naming), categorization will silently fall back to Other. Normalize at the boundary (e.g., filename = filename.lower()) before the lookup to make categorization consistent.

Suggested change

"""Determine category for a notebook based on filename."""

"""Determine category for a notebook based on filename."""

filename = filename.lower()

Copilot · 2026-02-06T23:45:10Z

+    "part-4-spatial-joins": "Getting Started",
+    # Analyzing Data
+    "clustering-dbscan": "Analyzing Data",
+    "getis-ord-gi*": "Analyzing Data",


Including * in a filename key implies the corresponding generated MDX/Notebook stem may contain *, which is error-prone in shells, globbing contexts, URLs, and some tooling. If the underlying notebook really is named with *, consider renaming it to a safer token (e.g., getis-ord-gi-star) and updating the mapping accordingly; otherwise, update the key to the actual normalized filename to avoid confusing future contributors.

Suggested change

"getis-ord-gi*": "Analyzing Data",

"getis-ord-gi-star": "Analyzing Data",

…CI enforcement) Combines the work from PR #125 and PR #118: - Add cleanup_orphaned_mdx.py script to remove orphaned MDX files when notebooks are deleted or renamed - Add check-notebooks.yml CI workflow to enforce that PRs modifying notebooks also update the navigation config - Dynamically discover notebook directories instead of hardcoding them - Use git add -A to stage deletions in the docs sync workflow - Include deleted file list in auto-generated docs PR descriptions - Add cleanup target to Makefile, run it before convert in preview/all - Update README to reflect NOTEBOOK_LOCATIONS config and document the orphan cleanup behavior

kadolor · 2026-02-21T00:19:47Z

Closing in favor of #129

kadolor added 2 commits February 6, 2026 14:59

Fixing the script so that lowercase slugs are generated, README is up…

14a2bad

…dated, and navigation is correctly mapped

new workflow action to prevent misc categorization of new notebooks

9188718

kadolor self-assigned this Feb 6, 2026

github-advanced-security AI found potential problems Feb 6, 2026

View reviewed changes

Comment thread .github/workflows/check-notebooks.yml Fixed

kadolor marked this pull request as draft February 6, 2026 23:43

Potential fix for code scanning alert no. 3: Workflow does not contai…

0bd0415

…n permissions Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

kadolor requested a review from Copilot February 6, 2026 23:43

kadolor mentioned this pull request Feb 6, 2026

Fixing the script so that lowercase slugs are generated, README is up… #124

Merged

Copilot AI reviewed Feb 6, 2026

View reviewed changes

kadolor mentioned this pull request Feb 21, 2026

feat: combine notebook workflow improvements (cleanup orphaned MDX + CI enforcement) #129

Open

kadolor closed this Feb 21, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

new workflow action to prevent misc categorization of new notebooks#125

new workflow action to prevent misc categorization of new notebooks#125
kadolor wants to merge 3 commits intomainfrom
add-new-workflow-action

kadolor commented Feb 6, 2026 •

edited

Loading

Uh oh!

gitnotebooks bot commented Feb 6, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 6, 2026

Uh oh!

Copilot AI Feb 6, 2026

Uh oh!

Copilot AI Feb 6, 2026

Uh oh!

Copilot AI Feb 6, 2026

Uh oh!

Copilot AI Feb 6, 2026

Uh oh!

Copilot AI Feb 6, 2026

Uh oh!

kadolor commented Feb 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

-          BASE_BRANCH: ${{ github.base_ref }}
-        run: |
-          echo "Comparing HEAD against origin/$BASE_BRANCH..."
-          # Get list of changed files between the PR branch and the base branch
-          CHANGED_FILES=$(git diff --name-only origin/$BASE_BRANCH HEAD)
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          echo "Comparing changes between BASE_SHA=$BASE_SHA and HEAD_SHA=$HEAD_SHA..."
+          # Get list of changed files between the PR base commit and the PR head commit
+          CHANGED_FILES=$(git diff --name-only "$BASE_SHA" "$HEAD_SHA")

		# Extract filenames without extensions for comparison
		HAS_IPYNB=$(echo "$CHANGED_FILES" \| grep '\.ipynb$' \| sed 's/\.ipynb$//' \|\| true)

-            echo "::error::⛔ FAILURE: The following notebooks are missing mappings in $CONFIG_FILE_PATH:$MISSING_MAPPING"
+            echo "⛔ FAILURE: The following notebooks are missing mappings in $CONFIG_FILE_PATH:"
+            # Interpret the '\n' escape sequences in MISSING_MAPPING as actual newlines
+            printf '%b\n' "$MISSING_MAPPING"
+            echo "::error::⛔ FAILURE: One or more notebooks are missing mappings in $CONFIG_FILE_PATH. See the list above for details."

		@@ -46,13 +64,7 @@

		def get_category(filename: str) -> str:
		"""Determine category for a notebook based on filename."""

	"""Determine category for a notebook based on filename."""
	"""Determine category for a notebook based on filename."""
	filename = filename.lower()

	"getis-ord-gi*": "Analyzing Data",
	"getis-ord-gi-star": "Analyzing Data",

Conversation

kadolor commented Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gitnotebooks bot commented Feb 6, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

kadolor commented Feb 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

kadolor commented Feb 6, 2026 •

edited

Loading