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
    - 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
    - file: basic_lessons/lesson1_exercise_answers.ipynb
    - file: basic_lessons/lesson2_exercise_answers.ipynb
    - file: basic_lessons/lesson3_exercise_answers.ipynb
    - file: basic_lessons/lesson4_exercise_answers.ipynb
    - file: basic_lessons/lesson5_exercise_answers.ipynb
    - file: other/dqrobotics.md
    - file: book.md
    - file: CHANGELOG.md
    - file: TODO.md

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.

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 the webpage
export BASE_URL="https://marinholab.github.io/OpenExecutableBooksRobotics"

cat myst.yml
python -m jupyter book build --html --execute

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

    # To prevent github actions from eating up too many enterprise minutes
    timeout-minutes: 5
    
    # 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