Book generation and deployment issue

[mhasoba]

See #129 (comment)

TBD

[mhasoba]

Automating Deployment with GitHub Actions

Proposal to use GitHub Actions to automate the book build and deployment:

1. Set Up Workflow: Create a GitHub Actions workflow that triggers on pushes to the main / master branch.

2. Build the Book: Configure the workflow to install Jupyter Book and build the project.

3. Deploy: Use the peaceiris/actions-gh-pages action or similar to deploy the contents of _build/html to the gh-pages branch.

Example Workflow Snippet can be found at: https://jupyterbook.org/en/stable/publish/gh-pages.html

Here is a possible GitHub Actions solution that includes support for R and Bash kernels (necessary for TMQB) generated using ChatGPT:

1. Create the GitHub Actions Workflow File

• Create a new file in your repository at .github/workflows/deploy-jupyter-book.yml.

2. Example GitHub Actions Workflow

name: Build and Deploy Jupyter Book

on:
  push:
    branches:
      - main  # Adjust to your deployment branch
  workflow_dispatch:  # Allows manual triggering

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    # Step 1: Check out the repository
    - name: Check out the repository
      uses: actions/checkout@v3

    # Step 2: Set up Python
    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.9'  # Adjust as needed

    # Step 3: Install dependencies
    - name: Install Python dependencies
      run: |
        python -m pip install --upgrade pip
        pip install jupyter-book
        pip install nbconvert  # For converting notebooks
        pip install jupyterlab  # Provides necessary extensions

    # Step 4: Set up R kernel
    - name: Set up R environment
      uses: r-lib/actions/setup-r@v2
      with:
        r-version: '4.2'  # Adjust version as needed

    - name: Install R packages for Jupyter
      run: |
        Rscript -e 'install.packages(c("IRkernel", "devtools"), repos="https://cloud.r-project.org/")'
        Rscript -e 'IRkernel::installspec(user = FALSE)'

    # Step 5: Install Bash kernel
    - name: Install Bash kernel
      run: |
        pip install bash_kernel
        python -m bash_kernel.install

    # Step 6: Build the Jupyter Book
    - name: Build the Jupyter Book
      run: |
        jupyter-book build . --all

    # Step 7: Deploy to GitHub Pages
    - name: Deploy to GitHub Pages
      uses: peaceiris/actions-gh-pages@v4
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./_build/html

Explanation of Each Step

• Check out the repository: Clones your GitHub repository so that the content is available to the workflow.
• Set up Python: Ensures that Python is available and installs jupyter-book and other Python dependencies.
• Set up R environment: Uses the r-lib/actions/setup-r action to install R and the necessary kernel (IRkernel).
• Install Bash kernel: Installs the Bash kernel using bash_kernel.
• Build the Jupyter Book: Runs jupyter-book build . to compile the book into the _build/html directory.
• Deploy to GitHub Pages: Uses the peaceiris/actions-gh-pages action to deploy the built book to GitHub Pages.
• Secrets: GitHub automatically provides GITHUB_TOKEN for authenticating the gh-pages action. Make sure your repository allows GitHub Actions to deploy content.

Customizing the Workflow

• Branch Name: Replace main with your branch name if your default branch differs.
• Python Version: Adjust the Python version as needed.
• R Packages: Add any additional R packages required by your notebooks under the Install R packages for Jupyter step.
• Environment Variables: Set additional environment variables if your build requires them.