Tracking: Numpy Tutorials

rowanc1 commented 3 months ago

There is interest from the numpy-tutorials project/team to investigate the mystmd CLI as an alternative for their tutorials. I think that this is an excellent additional usecase to assess any gaps that we have in the JupyterBook experience (#1000, #1106). In testing by @melissawm (here) The main experience works well, maintains execution, and generally has most features (I think?!) they are looking for.

I have done an assessment from my side that tries to capture the required improvements from MyST:

Issues

[ ] #1267
[ ] #1269 (maybe just documentation)
[x] #1268
[ ] #950

Missing Functionality

[ ] #100
[ ] #1338 (has been removed, but would have made the upgrade process smoother)

UI Assessment

I think staying closer to the pydata-theme here is advantageous, with the logo/icons/search in the left nav-pane and the launch buttons at the top. In addition we could have a top nav-bar that, for example, is shared between various independent sites.

[ ] #670
[ ] https://github.com/executablebooks/myst-theme/issues/362
[ ] https://github.com/executablebooks/myst-theme/issues/326
[ ] Adding a footer (copyright)
[ ] #1235
[ ] Simple details dropdowns from HTML should be less styled (currently they are similar to an admonition)
[ ] Better association between code output and input in the notebook render, this could be better from a styling perspective
[ ] #443

UI Opportunities

[ ] Adding a source to a figure/image directive (to capture attribution/licensing)

Compatibility Opportunities

[ ] Right now there are some advantages to keeping links to numpy/matplotlib docs as markdown links, we should also be able to recognize these links and upgrade them to intersphinx (e.g. to know if the page/ID continues to exist, which isn't checked in a link check as the hash is dropped). In addition to that, we could introduce a service that parses the HTML of those pages to give a similar hover-preview to that content for any myst site or wikipedia, that is a bit more of an ambitious target, but I think would make a unique, compelling and incremental upgrade path.

cc @fperez, @melissawm, @rossbar

rowanc1 commented 3 months ago

It is always nice to see some of the features work out of the box on new sites. For example, wiki links and being able to add abbreviations really easily (hopefully making the content more accessible for all readers!):

https://github.com/executablebooks/mystmd/assets/913249/2fcbf126-c671-4b5f-8651-20897df68a3d

@melissawm adding the following to the project config is how to get abbreviations showing up throughout the entire book:

project:
  abbreviations:
    LSTM: Long Short Term Memory network
    IMDB: Internet Movie Database
    AI: Artificial intelligence

agoose77 commented 3 months ago

This initiative is so exciting @rowanc1 @melissawm! It's so encouraging that much of the work is shared with the Jupyter Book efforts!

jupyter-book / mystmd