講義を DX する（その1）

Dec 1st, 2022 lifehack git github typescript deno

はじめに

現状（すでに過去であるが），講義は講義資料（スライドを PDF にしたもの）とサンプルコードで進めているが，下記で述べるような数多くの問題が発生している．

クラス数が少ないうちは人力で対応することができるが，オンラインオフライン混在で多くのクラスが同時進行する状況で手が回らなくなっている状況にある．

したがって，「状況に関わらず同質な講義が提供できる」「受講生講師チューターが楽をできる」「持続可能である」仕組みを考案して実現することとした．以下はその試行錯誤の記録である．

今回の DX

今回の DX （前半）により，下記の状況を達成する．

成果物

本ページで考案した仕組みを組み込んだサンプルを作成した．

講義資料はスライドから HTML に変更し，サンプルコードは資料内のダウンロードリンクからワンクリックでダウンロードが可能だ．

受講生は，デプロイ先の URL にアクセスするだけで受講に必要な情報にアクセスすることができるようになった．

現状

現在の講義資料とサンプルコードの展開は以下の手順を必要としている．

  1. 講義資料（スライド）を作成する．
  2. サンプルコードと同じディレクトリに入れる．
  3. 上記ディレクトリを圧縮する．
  4. 圧縮したディレクトリを Google ドライブの共有フォルダに保存する．
  5. 共有フォルダから zip ファイルをダウンロードする．
  6. zip ファイルを解凍する．

課題

以下のように，全員不幸になるタイミングが数多く報告されている．

スライドからコードをコピーした場合に予期せぬエラーが発生する．

レイアウトの制約上スライドとコードの区切りが整合しない．

講義資料（スライド）の修正時の工数が多い．

スライドとサンプルコードを個別に管理しなければならない．

資料の展開を任意のタイミングで行えない．

以前の講義内容（資料）を見たい場合，別ファイルを探してアクセスする必要がある．

課題の解決策

各課題に対して，下記のようなアプローチで検討した．

具体的な設計

上記の解決策を実現するため，下記の技術を用いることとした．

SSG「mdbook」を用いて講義資料作成する．

GitHub を用いて講義資料とデプロイの管理を行う．

GitHub Actions を用いてサンプルコード圧縮とデプロイを行う．

現時点で実現を目指すフロー

  1. マスターとなる講義資料とサンプルコードを事前に準備しておく．
  2. 新しいクラスが開始するタイミングで講義資料用のリポジトリを準備する．
  3. マスターの資料からクローンし，vs code 上でクラス毎にユニークとなる部分やデプロイ範囲を設定する．
  4. GitHub にディレクトリを push する．
  5. GitHub 上で main ブランチにマージする．
  6. （自動）GitHub Actions を用いて資料をビルドする
  7. （自動）サンプルコードを zip 圧縮し，講義資料とマージする．
  8. （自動）ビルド完了後，GitHub Pages を用いて自動でデプロイされる．
  9. （デプロイ URL は予め受講生に共有しておく．）
  10. デプロイされた資料からワンクリックでサンプルコードがダウンロードできる．

以降，講義準備時は毎回 3-5 を行うのみ．

これらの実現により，

つまり，全員が幸せになる．そして，フローを自作することが GEEK だ．

以下に詳細な内容を紹介する．

SSG「mdbook」を用いた講義資料作成．

「mdbook」は Rust 製の SSG フレームワークである．SSG を実現するフレームワークは数多くあるが，ドキュメント生成ツールとしての機能が必要十分であることと，筆者が Rust が好きという理由で採用した．

https://github.com/rust-lang/mdBook

特徴は下記のとおり．

ここでは特に変わった処理は必要ない．各講義毎にディレクトリを作成し，区切り毎に md ファイルをつくって解説を書いていくだけだ．

これを実現することで，謎の改行やページ区切りで混乱する苦行やファイルを管理する面倒な操作を過去のものとした．

やはり時代はテキストだ．環境に依存せず移植が容易なテキストこそ至高である．

GitHub を用いた講義資料とデプロイの管理．

GitHub Actions 用の yml ファイル内にデプロイのフローを記述することで GitHub Pages 上にデプロイすることが可能となる．

より具体的には，下記の流れでフローが実行される．

  1. 「main」ブランチに push されたタイミングでビルドコマンドを実行する．
  2. 「ビルドコマンドにより吐き出されたファイルがまとめられているディレクトリ」を「gh-pages」ブランチに push する．
  3. GitHub Pages に「gh-pages」ブランチをデプロイする．

実際の yml ファイルは以下のような記述となる（mdbook 公式のサンプルほぼそのまま）．

name: github pages

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2

      - name: Setup mdBook
        uses: peaceiris/actions-mdbook@v1
        with:
          mdbook-version: "0.4.8"
          # mdbook-version: 'latest'

      # mdファイルのビルド
      - run: mdbook build

      # ビルドされたファイル群をgh-pagesブランチにデプロイ
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/main'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./book

講師は下記手順で講義資料の準備を行うこととなる．

  1. develop ブランチで講義資料を準備する．
  2. 準備ができ次第，main ブランチへプルリクエストを送る．
  3. 任意のタイミングで main ブランチへのマージを行うことで，上記のフローが実行され，資料がデプロイされる．（マージ操作はモバイルのアプリケーションからでも実行することができる点がポイント）

これを実現することで，毎回の PDF 作成 → アップロードの手順や修正に伴う煩雑な作業を駆逐することができた．

GitHub Actions を用いたサンプルコード圧縮とデプロイ．

上記のフローでは，講義資料そのものはデプロイができるが，サンプルコードが含まれていない．

このままではサンプルコードは別途 Google ドライブなどに共有する必要がある．これでは，今回の狙いの半分しか達成されていない状況だ．

したがって，ビルドと同時にサンプルコードを zip 形式に圧縮し，デプロイするファイルにマージする処理が必要である．

しかし，これも GitHub Actions 内で実行可能だ．

yml ファイルに下記の処理を追加した．やっていることは必要な処理をシェルコマンドで実行しているだけである．

name: github pages

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2

      - name: Setup mdBook
        uses: peaceiris/actions-mdbook@v1
        with:
          mdbook-version: "0.4.8"
          # mdbook-version: 'latest'

      - run: mdbook build

      # 🔽 サンプルファイルをzip圧縮してビルドしたファイル群に追加する処理
      - run: |
          mkdir ./book/samples
          cd samples
          find . \! -name '*.zip' -type d -exec zip -r {}.zip {} \;
          mv *.zip ../book/samples

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/main'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./book

これにより，zip 圧縮されたサンプルコードのファイルが自動でデプロイされるようになった．

あとは，講義資料側に「zip ファイルのパスを指定したリンク」を設定しておけばワンクリックで zip ファイルをダウンロード可能である．

これを実現することで，講義の度に毎回 Google ドライブにアクセスするという面倒な手順をスキップできるようになった．

まとめと次の課題

今回の DX により，下記の状況を達成することができた．

しかし，実使用した結果，下記の課題が残っていることが判明した．

これでは持続可能な体勢とは言えないので，まだ改善が必要である．．！

講義を DX する（その 2）へ続く．．．