Adding base of OXBR.

Author: Murilo Marinho

CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 2025
+
+- I'm removing `spatialmath` from the tutorials and moving any old content to `legacy/spatialmath`. The original intention when adding this library was to facilitate more complex content in later parts of the module. With variable levels of programming knowledge in the standard cohort this is not possible, and the following issues were observed:
+   - `spatialmath` not being available as binary package in many distributions, causing students to have to compile the `wheel` even when using `pip`. 
+        - In Windows enviroments, for example, this means having a working VS Compiler installation which is not default and is beyond the scope of this module. 
+        - In any distribution, this could take several minutes and even fail depending on student's enviroments.
+   - Students tend to default to memorising the library functions instead of understanding the underlying mechanism, irrespective of how trivial the operations are. It is more pedagogical to rely on the matricial operations that they are expected to learn and reinforce that knowledge.
+
+- Remove all mentions of `import` in sample code, and keep them to explicit and isolated import cells. Despite the clear indication in the text that the `import` statement was merely illustrative, novice readers often default to copying and pasting chunks of example code causing extraneous `import` statements that result in unprofessional code that, beyond aesthetics, can cause all sorts of issues.

LICENSE

@@ -0,0 +1,123 @@
+# Making your own executable book 
+
+```{warning}
+  This notebook is a work in progress. This is based on `Jupyter Book 2.0` which is currently in alpha, meaning that
+  it might change considerably before release.
+```
+
+```{seealso}
+  - Jupyter book: https://next.jupyterbook.org
+  - MyST: https://mystmd.org/guide/
+```
+
+## Dependencies
+
+Remember to set a `venv` first. The Python policies are becoming evermore stringent in this regard.
+
+```commandline
+python -m venv venv
+source venv/bin/activate
+```
+
+Installation can be done as follows.
+
+```{important}
+  The `--pre` flag is important while this version is not released.
+```
+
+```commandline
+python -m pip install jupyter-book --pre
+```
+
+## Cloning or downloading the repository
+
+To clone, please use the usual.
+
+```commandline
+git clone https://github.com/MarinhoLab/OpenExecutableBooksRobotics.git
+```
+
+Further, the package can be downloaded from [here](https://github.com/MarinhoLab/OpenExecutableBooksRobotics/archive/refs/heads/main.zip).
+
+## Building the book
+
+### Live document
+
+```commandline
+jupyter book start
+```
+
+Then click on the link, output below
+
+```
+     ✨✨✨  Starting Book Theme  ✨✨✨
+
+
+
+🔌 Server started on port 3000!  🥳 🎉
+
+
+        👉  http://localhost:3000  👈
+
+```
+
+which usually, as described, connects to `http://localhost:3000`.
+
+### Building the HTML
+
+```
+jupyter book build --html
+```
+
+If needed, the page can be opened at `_build/html/index.html`.
+
+## Notebook configuration
+
+In this version of jupyter notebook, `myst.yml` is the soul of the book. It is very uncommon that `conf.py` is needed.
+
+```{literalinclude} myst.yml
+```
+
+Everything in `myst.yml` is standard, aside from the following block.
+
+```{literalinclude} myst.yml
+:start-at: #USING DQROBOTICS DEVEL [START]
+:end-at: #USING DQROBOTICS DEVEL [END]
+```
+
+This is a temporary solution to address notebooks that do not play well together. Currently, a jupyter book spawns one process
+of each notebook and results can be nondeterministic if notebooks can affect each other. More information can be seen
+[here](https://github.com/jupyter-book/mystmd/issues/1794).
+
+I'm combining that block with a simple use of `sed` to guarantee the initial lessons that use the stable version of `dqrobotics`
+run before lessons that need the development version of `dqrobotics.` For more information, see the file below.
+
+```{literalinclude} build_html.sh
+```
+
+We currently only need `conf.py` below for math commands in MySt documents.
+
+```{literalinclude} conf.py
+```
+
+## Deployment in GitHub
+
+```{important}
+  It is very common for GitHub Actions to change how it works internally. This can affect, for instance, the version of the
+  images run by the GitHub Actions runners, how GitHub Pages works, or how artifact upload works. If the workflow mentioned
+  herein no longer works in the future, it is important to look at initially newer versions of the imported actions.
+  Currently:
+  - `actions/checkout@v4`
+  - `actions/upload-pages-artifact@v3`
+  - `actions/configure-pages@v4`
+  - `actions/deploy-pages@v4`
+```
+
+This workflow is straightforward and effective. The only external action needed is to set, in your repository,
+`⚙Settings > Pages > Build and deployment > Source > GitHub Actions`.
+
+
+```{literalinclude} .github/workflows/notebook_to_html.yml
+```
+
+

M3logo_black.png

@@ -0,0 +1,25 @@
+#!/bin/bash
+
+# While 2.0 is not stable
+python -m pip install jupyter-book --pre
+
+# Otherwise the links will not be correctly set up for th webpage
+export BASE_URL="https://marinholab.github.io/OpenExecutableBooksRobotics"
+
+# This is a bit hacky.
+# https://github.com/orgs/jupyter-book/discussions/2055#discussioncomment-13250715
+# This is my temporary hacky solution
+
+# Run once without the devel
+cp myst.yml _myst.yml
+sed -i.bak '/\#USING DQROBOTICS DEVEL \[START\]/,/\#USING DQROBOTICS DEVEL \[END\]/d' myst.yml
+echo "RUN ONE, WITHOUT DQROBOTICS DEVEL PAGES"
+cat myst.yml
+python -m jupyter book build --html --execute
+
+# Run again with the devel. The cached should no longer collide
+mv _myst.yml myst.yml
+python -m jupyter book build --html --execute
+echo "RUN TWO, WITH DQROBOTICS DEVEL PAGES"
+cat myst.yml
+

M3logo_black.svg

@@ -0,0 +1,4 @@
+# https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
+myst_enable_extensions = [
+    "dollarmath"
+]

M3logo_white.svg

@@ -0,0 +1,21 @@
+#!/usr/bin/env python
+## From: https://stackoverflow.com/questions/45382122/how-to-count-lines-of-code-in-jupyter-notebook
+from json import load
+from sys import argv
+
+def loc(nb):
+    cells = load(open(nb))['cells']
+
+    wc = 0
+    for c in cells:
+        for a in c['source']:
+            x = str(a).split()
+            wc = wc + len(x)
+            print(f"--- {x} ---")
+    return wc
+
+def run(ipynb_files):
+    return sum(loc(nb) for nb in ipynb_files)
+
+if __name__ == '__main__':
+    print(run(argv[1:]))

book.md

@@ -0,0 +1,69 @@
+# See docs at: https://mystmd.org/guide/frontmatter
+version: 1
+
+project:
+  id: f420092a-e58c-429b-aca2-fb33c47059c7
+  jupyter: true # https://mystmd.org/guide/integrating-jupyter
+  title: "OXBR"
+  github: https://github.com/MarinhoLab/OpenExecutableBooksRobotics
+  math:
+    '\myvec': '\mathbf{\boldsymbol{ #1 }}'
+    '\mymatrix': '\mathbf{\boldsymbol{ #1 }}'
+    '\quat': '\mathbf{\boldsymbol{ #1 }}'
+    '\dual': '\varepsilon'
+  authors:
+    - name: Murilo M. Marinho
+      email: murilo.marinho@manchester.ac.uk
+      url: https://mmmarinho.github.io
+      # The LinkedIn key is listed in the docs but gives a warning and does nothing
+      # linkedin: www.linkedin.com/in/murilo-marques-marinho-046178252
+      # The GitHub key has no warning but also doesn't do anything
+      # github: https://github.com/mmmarinho
+      note: Lecturer in Robotics
+      orcid: 0000-0003-2795-9484
+      affiliations:
+      - id: MMM
+        institution: The University of Manchester
+        department: EEE
+        ror: 027m9bs27
+  license:
+    content:
+      id: CC-BY-NC-SA-4.0
+  toc:
+    - file: README.md
+    - title: "[Basic] Robotics using numpy"
+      children:
+        - file: basic_lessons/README.md
+        - file: basic_lessons/lesson1_tutorial.ipynb
+        - file: basic_lessons/lesson2_tutorial.ipynb
+        - file: basic_lessons/lesson3_tutorial.ipynb
+        - file: basic_lessons/lesson4_tutorial.ipynb
+        - file: basic_lessons/lesson5_tutorial.ipynb
+    - title: "[Advanced] DQ Robotics"
+      children:
+        - file: dqrobotics/README.md
+        - file: dqrobotics/lesson1/lesson_dq1_python_basics.ipynb
+        - file: dqrobotics/lesson2/lesson_dq2_quaternion_basics.ipynb
+        - file: dqrobotics/lesson3/lesson_dq3_dual_quaternion_basics_part1.ipynb
+        - file: dqrobotics/lesson4/lesson_dq4_dual_quaternion_basics_part2.ipynb
+        - file: dqrobotics/lesson5/lesson_dq5_robot_control_basics_part1.ipynb
+        - file: dqrobotics/lesson6/lesson_dq6_robot_control_basics_part2.ipynb
+        - file: dqrobotics/lesson7/lesson_dq7_robot_control_basics_part3.ipynb
+        - file: dqrobotics/lesson8/lesson_dq8_optimization_based_robot_control.ipynb
+    - file: book.md
+    - file: CHANGELOG.md
+    - file: TODO.md
+#USING DQROBOTICS DEVEL [START]
+    - title: "[Incomplete] Working chapters"
+      children:
+        - file: working/README.md
+        - file: working/adaptive_control.md
+#USING DQROBOTICS DEVEL [END]
+
+site:
+  template: book-theme
+  title: OXBR Website
+  options:
+    logo: M3logo_black.png
+    logo_dark: M3logo_white.svg
+    logo_text: "(Murilo's) OXBR"