Jupyter notebooks on gitlab pages
Tags: datascience, python, beginners
Published: 2022-09-30 15:52:16

## Problems
6. Some plotting packages' output (holoviews, Altair) are currently not always saved as a part of the notebook itself.
7. Sharing results with collaborators takes an extra step of extracting plots and putting them together in something like pdf or html  

## Solution: jupyter-book plus gitlab pages
Automatically save the output of a notebook in a common, shareable format. Figures are included, and not just matplotlib based ones! [Here is a small demo](https://mmyros-project-chirp.netlify.app/vanderpol_coupled_standalone.html)
 
## Set up jupyter-book on your computer
- Initialize [jupyterbook](jupyterbook.org) in your `projects` folder. Be in the folder above the `projects` folder: 

```shell
pip install -U jupyter-book cookiecutter sphinx myst_nb
jupyter-book create projects --cookiecutter
```

- Type through the prompts. Example is in screenshot above 

## Daily use
- Create some jupyter notebooks in your `my_cool_project` folder
- Add your newly created notebooks' names to the file `toc.yml` in the folder `my_cool_project`
- Compile jupyter code to html locally:

```shell
cd projects/my_cool_project
jb build my_cool_project
```

## Set up for jupyter-book on gitlab
- Create an empty repository `my_cool_project` in gitlab
- Upload the newly created folder `my_cool_project` to gitlab `my_cool_project` repository
   - Follow the section "Push an existing directory" that appears on gitlab when you create an empty project
   - You may have to substitute the `git init` step with:
    ```shell
    git init                              
    git symbolic-ref HEAD refs/heads/main
    ```
- Sync to gitlab 
```shell 
 git add * && git commit -m 'I did some work' && git push
```
A blue build icon should appear on gitlab and then change to a green checkmark. That means your pages are available at https://\<YourUsername\>.gitlab.io/\<RepoName\> (e.g. https://mmyros.gitlab.io/my_cool_project/)

### Gitlab pages CI debug
If a green checkmark never appears, or https://<YourUsername>.gitlab.io/RepoName does not work, edit `.gitlab-ci.yml` to contain the following, then commit and push like usual.
```yml
image: python:3.7                                                                                                                                                                                                  
                                                                                                                                                                                                                   
pages:                                                                                                                                                                                                             
  script:                                                                                                                                                                                                          
    - mv my_cool_project/_build/html/ public/                                                                                                                                                                      
  artifacts:                                                                                                                                                                                                       
    paths:                                                                                                                                                                                                         
      - public                                                                                                                                                                                               
                                                                                                                                                                                                                   
workflow:                                                                                                                                                                                                          
  rules:                                                                                                                                                                                                           
    - if: $CI_COMMIT_REF_NAME =~ /-wip$/  # Pipelines for branch or tag names that include -wip don't run                                                                                                          
      when: never                                                                                                                                                                                                  
    - if: '$CI_PIPELINE_SOURCE == "push"'                                                                                                                                                                          
                                             
```