jupyterbooks served from gitlab

[phaustin]

• figure out a workflow that would allow us to upload and download jupyterbooks to an eoas server, and create archived juputerbooks from git repos

• write an ansible playbook to spin up a jupyterhub from an archived jupyterbook

[slemonide]

I think the github repo link leads to medium article instead of the repo. Here is the correct one: https://github.com/loomchild/volume-backup

[slemonide]

Would we have people editing the book on the eoas server using jupyterhub? Are they going to save their work to git?

[phaustin]

possibly -- but probably just bind mount their home directories to a host folder. I'll go over the setup I've started here: https://github.com/phaustin/python_text at our meeting. Here's the config:
https://github.com/phaustin/python_text/blob/master/hub_image/jupyterhub_config.py

and here's the compose file:
https://github.com/phaustin/python_text/blob/master/docker-compose.yml

[slemonide]

How are the books going to be edited (the actual text, not when code from them is run in jupyther)?

[phaustin]

My workflow (which I need to write down someplace)

1. md files are always the cannonical source files
2. Default jupytext config pairing is ipynb,myst:
   https://github.com/eoas-ubc/eoas_tlef/blob/master/docs/support_files/jupyter_notebook_config.py#L45-L50
3. I never commit ipynb files to the repo, if there is more than about 30% python content, I also pair a py:percent file
   by overriding the default jupytext config: https://github.com/eoas-ubc/md2canvas/blob/master/examples/demo_quiz/jupytext.toml
4. I run the jupyter-book pre-commit package checks on every commit: https://github.com/eoas-ubc/md2canvas/blob/master/.pre-commit-config.yaml
5. I use watchdog to monitor the md files for changes and launch jb or sphinx builds, and live-server to refresh the browser
   https://github.com/eoas-ubc/jb_tools
6. I've been using emacs (with elpy) since about 1990, but I'm spending more time in vscode, especially to edit inside containers using the container extension. There's this myst extension: https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight
7. The extra myst markdown syntax doesn't render in notebooks, obviously. It's not too bad for us, but for students we're probably going to have to strip the non-commonmark myst syntax for some of the distributed notebooks
8. For the future -- jupyter has completely rewritten their extension package, which should make it possible to swap out their markdown parser for myst in v3.0. See https://discourse.jupyter.org/t/should-jupyter-recommend-a-text-based-representation-of-the-notebook/3273/23 and https://discourse.jupyter.org/t/julia-community-is-creating-a-new-notebook-format/5422/30
9. If I'm not running the apache container to display the html, I push to github.io using https://pypi.org/project/ghp-import/

[phaustin]

Also, here's that thread I mentioned about myst/knitr/pandoc design: executablebooks/meta#133 (reply in thread)

[phaustin]

latest commit works correctly by fetching md pages from github (first time need to right-click on rocket to open tab to log in, then right click again to open page on jupyterhub): https://github.com/phaustin/python_text/blob/3d2c33eb5ad20901ecfc4661a7e7911c5993efb4/notebooks_source/_config.yml#L16-L19

Next I'll make apache serve the pages and set up a dump git server to localhost instead of github

[phaustin]

On second thought -- fetching from github is good enough for now. I've moved some parameters from jupyterhub_config.py and docker-compose.yml into run_docker.sh and .env respectively -- pretty brittle though. Some parameters need to be duplicated in the two files -- see https://github.com/phaustin/python_text/blob/master/Readme.md#a-jupyerbook-example-served-from-localhost

[slemonide]

On second thought -- fetching from github is good enough for now. I've moved some parameters from jupyterhub_config.py and docker-compose.yml into run_docker.sh and .env respectively -- pretty brittle though. Some parameters need to be duplicated in the two files -- see https://github.com/phaustin/python_text/blob/master/Readme.md#a-jupyerbook-example-served-from-localhost

You can add export $(grep HUB_CONTAINER_NAME= .env | xargs) and export $(grep NETWORK_NAME= .env | xargs) to run_docker.sh as a quick way to solve the problem of having to keep configuration options separately.

See https://stackoverflow.com/questions/19331497/set-environment-variables-from-file-of-key-value-pairs

[phaustin]

nice --that's working on master. Also updated sphinx-book-theme launch button.

[phaustin]

Re jekyll -- note that we don't need any help formating the static pages -- jupyterbook is self-contained. A typical gh-pages deployment: https://github.com/eoas-ubc/eoas-ubc.github.io/tree/master
for https://eoas-ubc.github.io/ -- note the .nojekyll file to disable jekyll. I push the site to github using https://pypi.org/project/ghp-import/

[slemonide]

Yeah, I only used jekyll to test things out.