Add unstable/ directory with MyST text notebooks and converter script

- Convert 5 lessons + 5 exercise answers to .md MyST notebooks
- Add unstable/myst.yml and unstable/README.md
- Include convert_to_myst.py for reproducible conversion
- Build verified: myst build --execute --html succeeds for all 11 pages

Author: openhands-agent

convert_to_myst.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""Convert Jupyter notebooks (.ipynb) to MyST text notebooks (.md).
+
+Each code cell becomes a ````{code-cell}```` directive.
+Markdown cells are preserved as-is.
+Raw cells and latex macro cells are removed (handled by myst.yml).
+"""
+
+import json
+import re
+import sys
+from pathlib import Path
+
+
+def _join_source(source):
+    """Join cell source lines, ensuring proper newlines between them.
+
+    Handles both formats:
+    - ["line1\n", "line2\n"]  (original ipynb format)
+    - ["line1", "line2"]      (json.dump re-saved without trailing newlines)
+    """
+    if isinstance(source, str):
+        return source
+    parts = list(source)
+    if not parts:
+        return ""
+    # Check if lines already have trailing newlines
+    if parts and parts[0].endswith("\n"):
+        return "".join(parts)
+    # No trailing newlines — join with \n and add one at the end
+    return "\n".join(parts) + "\n"
+
+
+def notebook_to_myst(nb_path: Path, output_path: Path, title_prefix: str = ""):
+    """Convert a single notebook to a MyST text notebook."""
+    with open(nb_path) as f:
+        nb = json.load(f)
+
+    lines: list[str] = []
+
+    # Frontmatter
+    lines.append("---")
+    lines.append("kernelspec:")
+    lines.append("  name: python3")
+    lines.append("  display_name: 'Python 3'")
+    lines.append("---")
+    lines.append("")
+
+    for cell in nb["cells"]:
+        cell_type = cell["cell_type"]
+        source = _join_source(cell["source"])
+
+        if not source.strip():
+            continue
+
+        # Skip raw cells
+        if cell_type == "raw":
+            continue
+
+        # Skip latex macro definition cells
+        lower_src = source.lower().strip()
+        if "providecommand" in lower_src and ("myvec" in lower_src or "mymatrix" in lower_src):
+            continue
+
+        if cell_type == "markdown":
+            # Fix ipynb attachment syntax: ![img](attachment:img.png) -> ![img](img.png)
+            fixed = re.sub(
+                r'!\[(.*?)\]\(attachment:(.*?)\)',
+                r'![\1](\2)',
+                source,
+            )
+            lines.append(fixed.rstrip("\n"))
+            lines.append("")
+
+        elif cell_type == "code":
+            code = source.rstrip("\n")
+            lines.append("````{code-cell}")
+            lines.append(code)
+            lines.append("````")
+            lines.append("")
+
+    # Remove trailing blank lines but keep one
+    while len(lines) > 1 and not lines[-1].strip():
+        lines.pop()
+    lines.append("")
+
+    output_path.write_text("\n".join(lines), encoding="utf-8")
+    print(f"  {nb_path} -> {output_path}")
+
+
+def main():
+    base = Path(__file__).parent
+    src_dir = base / "basic_lessons"
+    dst_dir = base / "unstable"
+    dst_dir.mkdir(exist_ok=True)
+
+    # Copy images
+    for img in src_dir.glob("*.*"):
+        if img.suffix.lower() in (".png", ".svg"):
+            dst = dst_dir / img.name
+            dst.write_bytes(img.read_bytes())
+            print(f"  Copied {img.name}")
+
+    # Convert tutorial notebooks
+    tutorials = [
+        "lesson1_tutorial.ipynb",
+        "lesson2_tutorial.ipynb",
+        "lesson3_tutorial.ipynb",
+        "lesson4_tutorial.ipynb",
+        "lesson5_tutorial.ipynb",
+    ]
+
+    exercise_answers = [
+        "lesson1_exercise_answers.ipynb",
+        "lesson2_exercise_answers.ipynb",
+        "lesson3_exercise_answers.ipynb",
+        "lesson4_exercise_answers.ipynb",
+        "lesson5_exercise_answers.ipynb",
+    ]
+
+    print("Converting tutorials...")
+    for nb in tutorials:
+        src = src_dir / nb
+        dst = dst_dir / nb.replace(".ipynb", ".md")
+        notebook_to_myst(src, dst)
+
+    print("\nConverting exercise answers...")
+    for nb in exercise_answers:
+        src = src_dir / nb
+        dst = dst_dir / nb.replace(".ipynb", ".md")
+        notebook_to_myst(src, dst)
+
+    print("\nDone.")
+
+
+if __name__ == "__main__":
+    main()

unstable/.gitignore

@@ -0,0 +1,2 @@
+# MyST build artifacts
+_build/

unstable/Lesson4.png

@@ -0,0 +1,27 @@
+# [WIP] The Basics of Kinematic Modeling and Control of Serial-link Manipulators Using `numpy`
+
+> **Warning:** These are text-based (MyST) notebooks under active development. The canonical `.ipynb` versions remain in [`basic_lessons/`](../basic_lessons/).
+
+This directory contains the same five-lesson tutorial as [`basic_lessons/`](../basic_lessons/) but converted to
+[MyST text notebooks](https://mystmd.org/guide/notebooks-with-markdown). The content is identical; only the file format
+has changed from `.ipynb` to `.md` with `{code-cell}` directives.
+
+## Contents
+
+| Number | Title and Link | Content |
+|--------|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| 1 | [](./lesson1_tutorial.md) | Basic operations in Python and `numpy` |
+| 2 | [](./lesson2_tutorial.md) | Learn about elements and operations in $\mathbb{R}^n$, $SO(n)$, and $SE(n)$ with $n\in{\{2,3\}}$ related to positions, orientations, and poses, respectively. |
+| 3 | [](./lesson3_tutorial.md) | Learn about the composition of rigid body motion in series to obtain the forward kinematics model of a robotic manipulator. |
+| 4 | [](./lesson4_tutorial.md) | Learn about the first-order differential mapping $\dot{\myvec{x}}=\mymatrix{J}\dot{\myvec{q}}$ through the calculation of the Jacobian $\mymatrix{J}$. |
+| 5 | [](./lesson5_tutorial.md) | Employ the previous knowledge in all previous lessons to employ a Lyapunov-stable control law to move a manipulator in task space using configuration-space signals. |
+
+### Exercise Answers
+
+| Lesson | Link |
+|--------|------|
+| L1 | [](./lesson1_exercise_answers.md) |
+| L2 | [](./lesson2_exercise_answers.md) |
+| L3 | [](./lesson3_exercise_answers.md) |
+| L4 | [](./lesson4_exercise_answers.md) |
+| L5 | [](./lesson5_exercise_answers.md) |

unstable/Lesson4.svg

@@ -0,0 +1,50 @@
+---
+kernelspec:
+  name: python3
+  display_name: 'Python 3'
+---
+
+# L1 Exercise Answers
+
+*License: CC-BY-NC-SA 4.0*
+
+*Author: Murilo M. Marinho (murilo.marinho@manchester.ac.uk)*
+
+### I found an issue
+Thank you! Please report it at https://github.com/MarinhoLab/OpenExecutableBooksRobotics/issues
+
+### Latex Macros
+
+# Valid imports
+
+````{code-cell}
+from math import pi, sin, cos
+import numpy as np
+````
+
+# Exercises
+
+## Exercise 1
+
+````{code-cell}
+phi = pi/4.0
+
+e1 = sin(phi) + 4 * cos(phi / 5)
+
+# Printing the result is NOT a mandatory part of the answer.
+print(f'e1 = {e1}')
+````
+
+## Exercise 2
+
+````{code-cell}
+A2 = np.array([[5, 2],
+              [3, 5]])
+B2 = np.array([[5, 3],
+              [3, 8]])
+
+C2 = A2 + B2 + (A2 @ B2) - (B2 @ A2)
+
+# Printing the result is NOT a mandatory part of the answer.
+print(f'C2 = {C2}')
+````