We have lots of Jupyter Notebooks which serve as our user-guide/examples in two our projects. We use a certain number of technical terms throughout the notebooks, which we need to re-explain everytime, since there’s no particular order to the notebooks. For the sake of DRY (don’t repeat yourself), we were wondering if it’s possible to somehow tell Jupyter about these “keywords” and their definition, so that it automatically creates hyperlinks that point to a separate page to server as our “glossary”. I googled a bit, but to no avail. I’d really appreciate it if someone could let me know if that’s possible. Thanks!
It kind of depends on how you will be publishing them.
If these are consumed directly as notebooks in a jupyter client, and the definitions are non-trivial, probably maintaining a glossary.ipynb#<the-term> (or glossary/<the-term>.ipynb is going to be worth it in the long run.
If using something more automatic (but static), such as nbconvert, you could write your own preprocessor.
If using myst-nb to generate a full site, you might be able to find some existing sphinx extension.
3 Likes
Thank you for your quick reply. We’re using nbsphinx to generate static HTMLs, which are then hosted on GitHub Pages. Your response prompted me to google again, but more focused and narrowed down, and I ended up here. It seems that nbsphinx itself supports linking to other notebooks. So, I think we’ll go with your solution of creating a separate glossary notebook, and then use the linking syntax go generate hyperlinks. Thanks once again!
Welp, I can highly recommend myst-nb over nbsphinx: it’s smoothed out many of the historical issues I’ve had with nbsphinx around complicated formatting. It does seem to be evolving a bit more rapidly, though, so it is possible to get unexpected new “features” if you don’t lock your versions down.
1 Like
You know what, the other day, we were trying to add nice adminitions (hint, warning, etc.) to the notebooks, and found myst-nb after some googling, but didn’t realize it wasn’t just for admonitions! So, we tried to make it work with nbsphinx, and sure enough, it complained that ipynb files are being handled by another extension, or something along these lines. Anyway, we couldn’t decipher the error message, but now that you’re saying myst-nb is basically nbsphinx but better, it all makes sense. I’ll definitely look into it, but since we want to publish a major release for one of our software soon (OpenPNM), we’ll stick to nbsphinx fow now, but once v3 is released, I’ll start migrating from nbsphinx to myst-nb, hopefully we shouldn’t change much for the transition.
Anyway, thank you so much, and indeed myst-nb seems to be an amazing project!
2 Likes