Making your own executable book

Dependencies¶

Remember to set a venv first. The Python policies are becoming evermore stringent in this regard.

python -m venv venv
source venv/bin/activate

Installation can be done as follows.

python -m pip install jupyter-book --pre

Cloning or downloading the repository¶

To clone, please use the usual.

git clone https://github.com/MarinhoLab/OpenExecutableBooksRobotics.git

Further, the package can be downloaded from here.

Building the book¶

Live document¶

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.

myst.yml

# 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"

Everything in myst.yml is standard, aside from the following block.

myst.yml

#USING DQROBOTICS DEVEL [START]
    - title: "[Incomplete] Working chapters"
      children:
        - file: working/README.md
        - file: working/adaptive_control.md
#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.

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.

build_html.sh

#!/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

We currently only need conf.py below for math commands in MySt documents.

conf.py

# https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
myst_enable_extensions = [
    "dollarmath"
]

Deployment in GitHub¶

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.

notebook_to_html.yml

# This is a basic workflow to help you get started with Actions

name: Jupyter Book

# Controls when the workflow will run
on:
  # Triggers the workflow on push or pull request events but only for the "main" branch
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:



# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest
    
    # https://github.com/actions/starter-workflows/blob/55eb18560f57898549b12afa6defe7cc79705d6a/pages/static.yml#L13
    permissions:
      contents: read
      pages: write
      id-token: write

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks out your repository under $GITHUB_WORKSPACE, so your job can access it
      - uses: actions/checkout@v4

      # Runs a set of commands using the runner's shell
      # https://mystmd.org/guide/deployment-github-pages#fn-except-custom-domains
      - name: Install dependencies and build page
        run: |
          chmod +x build_html.sh
          ./build_html.sh

      # https://jupyterbook.org/en/stable/publish/gh-pages.html
      # Upload the book's HTML as an artifact
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: "_build/html"

      # https://github.com/actions/deploy-pages/issues/305
      - name: Configure Pages
        uses: actions/configure-pages@v4
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

[Advanced] DQ Robotics

DQ8 Optimization-based Robot Control

[Advanced] DQ Robotics

Changelog