Hello! I’m helping to run the NASA CryoCloud (2i2c JupyterHub) and to push open science in NASA Cryosphere communities. My team and I have created a JupyterBook for our community, but I keep getting questions from NASA community leads about the pluses and minuses of Quarto v JupyterBook. I have collected some ideas, but I was wondering if anyone here had thoughts. Thank you in advance!
2 Likes
I’d love to hear any ideas you’ve already compiled @tsnow03! For UW hackweeks we embraced Jupyterbook partly because Quarto hadn’t really appeared yet, but it seems like yet another great utility.
One pain point we’ve had from hackweeks in my opinion is the discrepancy between 1: Rendering notebooks on a website versus 2: Executing the same notebooks in the jupyterlab UI. Specifically, there is a mismatch in appearance due to what ‘flavors of markdown’ and advanced rendering is supported. This project looks promising as an attempt to close that gap GitHub - executablebooks/jupyterlab-myst: Integrating MyST functionality in Jupyter Lab !
But I should say, Jupyterbook has been wonderful for making content more accessible!! Search and navigation of well-rendered jupyter notebooks is so much better than just a collection of notebooks in a git repository!
We use JupyterBook for the Pythia Cookbooks and I think it’s an excellent tool. I can echo @scottyhq’s comments about rendered differences causing some irritation, and I’m glad to hear about the jupyterlab-myst project!
I don’t know much about Quarto and I’d be glad to hear others’ opinions. Looks interesting at first glance!
1 Like
At Openscapes we’ve been using Quarto because most of their community are R users and they are more familiar with that stack. We also intend to produce tutorials in at least 3 different languages (Python, R, Julia) and I’m not sure how easy that integration is with Jupyterbook but with Quarto is fairly simple.
I think both are great tools although Quarto has the advantage of being backed by Posit(formerly RStudio) and that makes it more polished for the end user. Side note: It would be cool to have a blog post comparing these tools for technical writing.
I worked as the GitHub helper at a recent SnowEx hackweek (with scotthq). I am familiar with both Jupyterbooks and Quarto. For me, the version control for Jupyter notebooks was so painful. The solutions to not sync the output (figures etc) in the notebook up to GitHub were cumbersome. I am used to Quarto qmd files and version control and the appearance of the output locally and in the rendering is the same. Note you can have ipnb files in a Quarto book, and I assume the same version-control/rendering issues are there. For example: EarthData Cloud Cookbook - NASA Earthdata Cloud Cookbook
That said I think the issues I saw were specific to a hackweek where there was rapid updating of the same notebook by multiple team members. In this situation, members would look at a notebook wo changing it, but Git would say it was changed and there was a merge conflict due to the XML associated with code output (say plots). These type of merge conflicts don’t arise with qmd files since they are flat ascii.
If you have a book with fairly static info and one person working on a ipynb file for your book, I don’t think run into these issues.
1 Like
Thanks @Elizabeth_Holmes_NOA I agree with your points but wanted to point out that nbdev solves some of these, particularly around merge conflicts and stripping memory addresses: nbdev - Git-Friendly Jupyter
That said it is definitely best to strip outputs when version controlling notebooks.
Now if we can have Xarray reprs be deterministic, that would solve even more issues!
Oh, we found solutions to this problem with the notebooks. But version control is not something one ever has to think about with qmd files.
Well as long as the rendering of the qmd files is happening on the “server” side (not sure if server is the right word). On my Quarto books it happens via a GitHub Action. Depending on what is in that qmd file, there may be a bit of caching you want to do so rendering doesn’t take forever. For my personal projects, I would render locally and push but in a hackweek, I wouldn’t want the participants to have to think about that.
But I guess that is a difference that a Jupyter notebook user might not like. If I download a ipynb file, I could see the outputs in that file if they were included. But a qmd file is ascii and so I need to render locally before I see all the output. Quarto does have a “visual” mode that looks kind of like a Jupyter notebook but I think it is still “flat” so you still have to re-render locally before you will see the outputs.
2 Likes
Fyi, there has been some discussion of adding features to nbdev/quarto to generate “multiple flavors” of output notebooks. More info here:
1 Like