You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: AGENTS.md
+54-99Lines changed: 54 additions & 99 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,99 +2,60 @@
2
2
3
3
## Overview
4
4
5
-
**Open Executable Books in Robotics** is a collection of Jupyter notebooks teaching kinematic modelling and control of serial-link robotic manipulators. The project is licensed under [CC-BY-NC-SA 4.0](LICENSE) and hosted at <https://github.com/MarinhoLab/OpenExecutableBooksRobotics>.
5
+
**Open Executable Books in Robotics** is a collection of MyST text notebooks teaching kinematic modelling and control of serial-link robotic manipulators. The project is licensed under [CC-BY-NC-SA 4.0](LICENSE) and hosted at <https://github.com/MarinhoLab/OpenExecutableBooksRobotics>.
|`_build/`| Build artifacts (excluded from git via `unstable/.gitignore`) |
18
+
|`_build/`| Build artifacts (excluded from git) |
22
19
23
20
---
24
21
25
-
## Modifying `.ipynb` Files
22
+
## Modifying MyST Text Notebooks
26
23
27
-
Jupyter notebooks are JSON files. Every cell's `source` field is a **list of strings**, where **each string must end with `\n`** (trailing newline). This is critical:
24
+
Lessons are [MyST text notebooks](https://mystmd.org/guide/notebooks-with-markdown) — plain Markdown files with `{code-cell}` directives. They are version-control friendly and human-readable.
28
25
29
-
### Correct format (renders properly in Jupyter):
30
-
```json
31
-
"source": [
32
-
"# L1 A quick Python refresher\n",
33
-
"\n",
34
-
"*License: CC-BY-NC-SA 4.0*\n",
35
-
"\n",
36
-
"### Prerequisites\n",
37
-
"The user of this notebook is expected to have prior knowledge in\n"
38
-
]
39
-
```
40
-
41
-
### Broken format (renders as one concatenated line):
42
-
```json
43
-
"source": [
44
-
"# L1 A quick Python refresher",
45
-
"",
46
-
"*License: CC-BY-NC-SA 4.0*",
47
-
""
48
-
]
49
-
```
26
+
### Structure
50
27
51
-
### When editing notebooks programmatically:
52
-
1. Load with `json.load()`, modify `cell['source']` entries.
53
-
2.**Every source line must end with `\n`** before writing back.
54
-
3. Save with `json.dump(nb, f, indent=1)` (single-space indent is standard).
55
-
4. Clear execution state on code cells to avoid stale output:
56
-
```python
57
-
cell['outputs'] = []
58
-
cell['execution_count'] =None
59
-
```
60
-
61
-
### When editing notebooks manually:
62
-
- Use a notebook editor (Jupyter, VSCode, or nbconvert) rather than raw text edits.
63
-
- If editing raw JSON, always verify trailing `\n` on source lines.
64
-
65
-
### Cell types:
66
-
| Type | Purpose |
67
-
|------|---------|
68
-
|`markdown`| Text, equations, images, headings |
69
-
|`code`| Python cells (numpy, math) |
70
-
|`raw`| Raw LaTeX macro definitions (`\providecommand`) |
71
-
72
-
### LaTeX macros:
73
-
Custom macros (`\myvec`, `\mymatrix`, `\quat`, `\dual`) are defined in two places:
74
-
1. As **raw cells** in each notebook (for Jupyter/LaTeX rendering)
75
-
2. In **`myst.yml`** under `project.math` (for MyST rendering)
28
+
Each `.md` lesson file begins with YAML frontmatter declaring the kernel:
76
29
30
+
```yaml
31
+
---
32
+
kernelspec:
33
+
name: python3
34
+
display_name: 'Python 3'
77
35
---
36
+
```
78
37
79
-
## Converting to MyST Text Notebooks
38
+
Code cells are delimited with `{code-cell}` directives:
80
39
81
-
Run the converter script to regenerate `unstable/*.md` from the canonical notebooks:
40
+
````markdown
41
+
````{code-cell}
42
+
import numpy as np
43
+
x = np.array([1, 2, 3])
44
+
````
45
+
````
82
46
83
-
```bash
84
-
python3 convert_to_myst.py
85
-
```
47
+
### Editing guidelines
86
48
87
-
This script:
88
-
- Copies images (`Lesson4.png`, `Lesson4.svg`) to `unstable/`
- Handles both trailing-newline and no-trailing-newline source formats
49
+
- Edit `.md` files directly — they are plain text.
50
+
- Every lesson should follow the header format convention (see below).
51
+
- Keep code cells focused and self-contained.
52
+
- LaTeX equations use inline `$...$` or display `$$...$$` syntax with the `dollarmath` MyST extension enabled in `conf.py`.
53
+
- Custom macros (`\myvec`, `\mymatrix`, `\quat`, `\dual`) are defined in `myst.yml` under `project.math`.
93
54
94
-
### MyST Compatibility Notes
55
+
### Image references
95
56
96
-
-**`%%capture` magic is not supported** in MyST text notebooks. The converter may produce cells containing `%%capture` (a Jupyter magic that suppresses output). These must be removed manually from the generated `.md` files, as MyST does not support this magic and the cell will fail to execute.
97
-
-After regenerating with `convert_to_myst.py`, check all unstable `.md` files for `%%capture` and remove those lines.
57
+
-Use relative paths: `` (relative to `basic_lessons/`)
58
+
-Images (`Lesson4.png`, `Lesson4.svg`) live alongside the lesson files in `basic_lessons/`.
| 1 |[](./lesson1_tutorial.ipynb)| Basic operations in Python and `numpy`|
18
-
| 2 |[](./lesson2_tutorial.ipynb)| 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. |
19
-
| 3 |[](./lesson3_tutorial.ipynb)| Learn about the composition of rigid body motion in series to obtain the forward kinematics model of a robotic manipulator, mapping their configuration space $\myvec{q}\in\mathbb{R}^n$ into their task space $\myvec{x}\in\mathbb{R}^m$. |
20
-
| 4 |[](./lesson4_tutorial.ipynb)| Learn about the first-order differential mapping $\dot{\myvec{x}}=\mymatrix{J}\dot{\myvec{q}}$ between joint space and task space velocities through the calculation of the Jacobian $\mymatrix{J}$. |
21
-
| 5 |[](./lesson5_tutorial.ipynb)| 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. |
18
+
| 0 |[](./lesson0_tutorial.md)| Setting up the virtual environment and installing all required dependencies. |
19
+
| 1 |[](./lesson1_tutorial.md)| Basic operations in Python and `numpy`|
20
+
| 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. |
21
+
| 3 |[](./lesson3_tutorial.md)| Learn about the composition of rigid body motion in series to obtain the forward kinematics model of a robotic manipulator, mapping their configuration space $\myvec{q}\in\mathbb{R}^n$ into their task space $\myvec{x}\in\mathbb{R}^m$. |
22
+
| 4 |[](./lesson4_tutorial.md)| Learn about the first-order differential mapping $\dot{\myvec{x}}=\mymatrix{J}\dot{\myvec{q}}$ between joint space and task space velocities through the calculation of the Jacobian $\mymatrix{J}$. |
23
+
| 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. |
0 commit comments