github action으로 Jupyter book 자동 배포하기

Jupyter book을 작업하다보면 jupyter-book build 명령어를 통하여 작업한 내용을 빌드하고

ghp-import 모듈을 사용하여 빌드된 페이지를 push 해주는 작업을 반복해야지 적용됩니다.

 

https://jupyterbook.org/en/stable/publish/gh-pages.html

위 페이지 내용을 확인하면 github action을 사용하여 작업물이 push 되면 바로 반복 작업하던 빌드 및 push를 자동화 할 수 있습니다.

 

제가 진행한 방법도 정리하였습니다.

 

먼저 작업하는 Jupyter book 저장소 최상단에 requirements.txt를 추가합니다.

ghp-import==2.1.0 pydata-sphinx-theme==0.13.1 jupyter-book==0.15.1

Jupyter book을 빌드하기 위한 Dependency를 작성합니다. (저는 위 버전으로 사용 중입니다.)

 

Jupyter book 저장소에서 Actions → New workflow를 선택합니다.

많은 Action 템플릿이 있지만 전부 작성해주겠습니다.

상단의 set up a workflow yourself 를 선택합니다.

main.yml 이라는 .github/workflows 하위 경로에 작성하도록 나옵니다.

파일명은 원하는 이름으로 설정하면됩니다.

이제 github action yml 파일을 작성해보겠습니다.

yml 파일은 yaml 이라는 데이터 직렬화 언어로 config 등에 많이 사용됩니다.

name: deploy-book

# Only run this when the master branch changes
on:
  push:
    branches:
    - master
    # If your git repository has the Jupyter Book within some-subfolder next to
    # unrelated files, you can make this run only if a file within that specific
    # folder has been modified.
    #
    # paths:
    # - some-subfolder/**

name에 action 이름을 설정합니다.

on: 하위에는 github에 어떤 동작이 들어왔을 때 동작할 지 설정합니다.

master branch에 push가 들어왔을 때 동작하도록 설정하였습니다.

 

# This job installs dependencies, builds the book, and pushes it to `gh-pages`
jobs:
  deploy-book:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2

    # Install dependencies
    - name: Set up Python 3.8
      uses: actions/setup-python@v2
      with:
        python-version: 3.8

    - name: Install dependencies
      run: |
        pip install -r requirements.txt
    # Build the book
    - name: Build the book
      run: |
        jupyter-book build ./book
    # Push the book's HTML to github-pages
    - name: GitHub Pages action
      uses: peaceiris/actions-gh-pages@v3.6.1
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./book/_build/html

jobs는 어떤 작업들을 진행할 지 설정합니다.

deploy-book 이라는 job을 선언해주었고 runs-on에는 ubuntu에서 동작하도록 설정하였습니다.

 

steps는 어떤 스탭으로 작업을 진행할지 설정합니다.

uses를 통하여 Marketplace에 등록된 기능 가져와서 사용합니다.

actions/checkout@v2는 저장소를 checkout 받는 action입니다.

actions/setup-python@v2는 python 설치 및 PATH 환경 변수에 command-line으로 사용할 수 있게 추가합니다.

저는 3.8 버전을 설치하도록 하였습니다.

 

다음은 Dependency를 설치합니다.

run 을 통하여 command를 실행할 수 있습니다.

필요한 Dependency를 저장소 최상단의 requirements.txt에 모두 작성해두었으니 아래 명령어로 설치하도록 설정합니다.

pip install -r requirements.txt

 

다음은 Jupyter book을 빌드합니다.

jupyter-book build [빌드할 book Root 경로]

 

빌드 완료 후  peaceiris/actions-gh-pages@v3.6.1 action을 통하여 GitHub Pages action을 통하여 gh-pages 브랜치에 빌드 결과물을 올리도록 합니다.

publish_dir: [build 된 html 폴더]

이때 publish_dir을 build 결과가 있는 html 폴더로 설정해줍니다.

 

아래는 제가 작성한 전체 내용입니다.

name: deploy-book

# Only run this when the master branch changes
on:
  push:
    branches:
    - master
    # If your git repository has the Jupyter Book within some-subfolder next to
    # unrelated files, you can make this run only if a file within that specific
    # folder has been modified.
    #
    # paths:
    # - some-subfolder/**

# This job installs dependencies, builds the book, and pushes it to `gh-pages`
jobs:
  deploy-book:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2

    # Install dependencies
    - name: Set up Python 3.8
      uses: actions/setup-python@v2
      with:
        python-version: 3.8

    - name: Install dependencies
      run: |
        pip install -r requirements.txt
    # Build the book
    - name: Build the book
      run: |
        jupyter-book build ./book
    # Push the book's HTML to github-pages
    - name: GitHub Pages action
      uses: peaceiris/actions-gh-pages@v3.6.1
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./book/_build/html

작성을 완료하였다면 Start commit 를 눌러 적용합니다.

그럼 deploy-book 이라는 workflow가 생기고 저장소에 작업 내용이 push 될 때 마다 자동으로 빌드 및 배포 동작을 합니다.