Tracking: Numpy Tutorials

[rowanc1]

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

• Differences between KaTeX and MathJax (underscore in text math) #1267
• Flexibly configure base url #1269 (maybe just documentation)
• Configuration option to exclude files/patterns #1268
• Rewrite internal links to include .html for static html (based on config) #950

Missing Functionality

• Support Search in MyST Sites #100
• Support tableofcontents, toctree directives #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.

• Support folder hierarchies and nested files in URLs without flattening them #670
• Support for icon links for social, github, external links, etc myst-theme#362
• Add an "Edit this page" button myst-theme#326
• Adding a footer (copyright)
• Launch buttons for Binder and JupyterHub #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
• Thebe integration: Modify sources #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]

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!):

numpy-tutorials.mp4

@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]

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