Running list of Jupyter Book questions

[adowling2]

Questions:

• [x] How to add "open in Colab" badge/button?
• [x] What are best practices for storing data? How to get said data to load in Colab?
• [x] What are the best practices for getting images to load in Colab?
• [x] How to handle notebooks that should throw errors intentionally (e.g., illustrate syntax mistake)

[adowling2]

data -- similar approach to nbpages images -- relative addresses work! not sure how it works behind the scenes look for version of pytest for notebooks

[adowling2]

Always use double dollar signs for math Look into different annotation styles in Jupter Book, see if it translates to nbpages See if this translates to Colab okay:

• https://jupyterbook.org/en/stable/content/content-blocks.html
• https://jupyterbook.org/en/stable/content/content-blocks.html?highlight=admonitions#html-admonitions

[adowling2]

Here is how to remove content: https://jupyterbook.org/en/stable/interactive/hiding.html

Easily edit tags in Jupyter Book: https://jupyterbook.org/en/stable/content/metadata.html#jupyter-cell-tags

Finding: removing or hiding cells does NOT remove the content from the source notebooks; the hidden/removed content is still available in Colab

[jckantor]

"Open in Colab" menu items is configured in _config.yml

# Launch on Google Colab button
launch_buttons:
    notebook_interface: "classic"
    colab_url: "https://colab.research.google.com"

[jckantor]

See https://github.com/jckantor/nbpages/blob/master/notebooks/nb_lite.ipynb for examples of how to manipulated cells based on tags and content.

[adowling2]

@jckantor Thank you. This is super helpful.

[jckantor]

I updated https://github.com/jckantor/nbpages/blob/master/notebooks/nb_lite.ipynb to show how to execute a notebook from python, and to allow errors and save the result.

[adowling2]

Nice! I found the correct configuration option in the Jupyter Book documentation to keep executing a notebook after an error.

[jckantor]

Very nice!

On May 4, 2022, at 10:22 PM, Alex Dowling @.***> wrote:

Nice! I found the correct configuration option in the Jupyter Book documentation to keep executing a notebook after an error.

— Reply to this email directly, view it on GitHub https://github.com/ndcbe/data-and-computing/issues/1#issuecomment-1118103977, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAYYECZ6WK3BSSF7UYWT27LVIMWIFANCNFSM5U4WTB7A. You are receiving this because you were mentioned.

[E-Ream]

Two general repeated issues to look into further:

• [ ] Highlighted box markdowns don't correctly format the $ $ math once published on the Github website, despite formatting correctly in Jupyter Lab
• [ ] Images appear in the Github website notebooks but do not appear once the notebook is opened in Colab

[E-Ream]

@adowling2 @jkeane14 In looking more into the first of the two above issues... The LaTeX math with $ and $$ seems to work sometimes in the published notebooks and not at other times, seemingly without reason as the code format is consistent throughout. I found this article that includes a script to run to allow MathJax to work its magic on the LaTeX for our GitHub pages website. I'm not sure if this is already being run but it could potentially solve this issue?

Suggested script to run:

Edit (AD, July 5, 2022):

I am trying admonitions. Not sure if all of these are supported: https://pradyunsg.me/furo/reference/admonitions/

[adowling2]

@jckantor Do you have any suggestions on getting images in a \media folder in Jupyter Book to load in Colab? The images are being included correctly in the HTML website. But they are missing when we hit the "open in Colab" button. Have you come up with a good workaround?

[jckantor]

@adowling2 I looked at this notebook ... https://ndcbe.github.io/data-and-computing/notebooks/02-publish/01-Modeling-Systems-of-Linear-Equations.html which has an image in the media folder. The reason the image is not opening on Colab is that the image uses a relative address for the media folder assuming the image is stored locally. It's not uploaded to Colab, so it is not local to Colab. The fix I've used is to reference the image with a URL referencing the book. In this case, changing

to

should do the trick.

[adowling2]

@jckantor Any thoughts on how to automate the URL replacement using this script? https://github.com/ndcbe/data-and-computing/blob/main/scripts/process_notebooks.py

This way it would be easy to debug new notebooks locally while still having the version in the "publish" folders useable for Colab.

[jckantor]

I think this bit of code would do the trick ...

# replace links to media with urls
IMAGE = "!\[(.*?)\]\(\.\./\.\./media/(.*\.*).*?\)"
for cell in nb.cells:
    if cell.cell_type == "markdown" and re.findall(IMAGE, cell.source):
        cell.source = re.sub(IMAGE, r'!(\1)[https://ndcbe.github.io/data-and-computing/_images/\2]', cell.source)

I created a new branch "kantor" with this change. That link hardcodes the repository name, so you may wish modify this so it is easier to reconfigure for other repositories. The idea is just to find the markdown links, extract two groups, then replace with a new markdown image link using a url to the public jupyterbook.

[jckantor]

Oops ... needed to fix a blunder ... here's the code snippet ...

# replace links to media with urls
IMAGE = "!\[(.*?)\]\(\.\./\.\./media/(.*\.*).*?\)"
for cell in nb.cells:
    if cell.cell_type == "markdown" and re.findall(IMAGE, cell.source):
        cell.source = re.sub(IMAGE, r'![\1](https://ndcbe.github.io/data-and-computing/_images/\2)', cell.source)

[jckantor]

I've cleaned up the regular expression, look in the "kantor" branch.

[adowling2]

@E-Ream With much help from @jckantor, we got the images to load in Colab. I published to the website ~10 minutes ago and it seems to be working.

[jckantor]

@adowling2 Great! I also added a second script, lint.py, that checks URLs for bad or invalid links. It looks for all URLs in the markdown cells, attempts to get each URL, then reports any problems. The regular expression to pick out URLs could use more refinement.

There are a few other checks that might be useful, such as checking if there are any media files that are not referenced, checking line lengths in code cells, indexing things, anything that may b useful check.