DEV Community

Cover image for Jupyter notebooks on gitlab pages
Max Myroshnychenko
Max Myroshnychenko

Posted on

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
Enter fullscreen mode Exit fullscreen mode
  • 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

Enter fullscreen mode Exit fullscreen mode

Top comments (0)