jupyter-book
jupyter-book copied to clipboard
executablebooks
Update MyST-NB to 0.16
Context
Currently, we pin MyST-NB to 0.13 here:
https://github.com/executablebooks/jupyter-book/blob/f7d1e42ffab244432f2bd803413c3de275504ffa/pyproject.toml#L36
However, it has since made a few releases and is now at 0.16. I'm not sure what exactly has changed between them, but in particular 0.14 introduced some breaking changes so there are likely both things to change in our documentation as well as in the test suite.
Proposal
We should update this pin to 0.16 and update our documentation+tests accordingly. Here are the changelogs from each release in case it's helpful in making the change:
- https://github.com/executablebooks/MyST-NB/releases/tag/v0.14.0
- https://github.com/executablebooks/MyST-NB/releases/tag/v0.15.0
- https://github.com/executablebooks/MyST-NB/releases/tag/v0.16.0
I think there are three things we want to do as part of this:
- Make the test suite pass w/ new MyST-NB
- Update the documentation to reflect the breaking changes
- Update the documentation to reflect the new additions/features
I think there are three things we want to do as part of this:
well I would also add to this, a major thing is how to update the _config.yml to account for the changes, and ideally have it so people can "auto-update" theirs.
As I've just mentioned in #1825, the way the documentation is duplicated here, and the way the config is organised, makes it really difficult to upstream any significant changes, especially in a way that is easy for users to migrate.
Both #1728 and #1748 would be really helpful here, but I just keep getting side-tracked/stuck in how to do this in a nice way.
As an additional note, it would also be nice if the _config.yml had a version number key, to easily know whether it needs migrating.
What is the minimal step forward that we can take to bring the latest myst-nb / myst-parser into Jupyter Book without introducing major problems? I think this problem will just get bigger and bigger as the diff between the released vs. supported versions gets bigger.
We can talk about it today/tomorrow at euroscipy 😄 (be there at 11).
But I think it's a balance, between doing something, and making it so this is (a) a smooth transition for users and (b) easier in the future, and we don't end up in the same situation.