Jupyter notebooks on gitlab pages

Problems

1. Some plotting packages' output (holoviews, Altair) are currently not always saved as a part of the notebook itself.
2. 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

Set up jupyter-book on your computer

• Initialize jupyterbook in your projects folder. Be in the folder above the projects folder:

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:

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:

  git init                              
  git symbolic-ref HEAD refs/heads/main
  

• Sync to gitlab
  
  

 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://.gitlab.io/RepoName does not work, edit .gitlab-ci.yml to contain the following, then commit and push like usual.

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"'