🆙 Upgrade Jupyter Books in myst init

[agoose77]

With the goal of running Jupyter Book on top of MyST, we need the ability to upgrade a book's configuration and TOC to myst.yml.

This PR adds a Jupyter-Book upgrade path when:

1. myst init is invoked and
2. the current directory does not contain a myst.yml and
3. the current directory contains a _config.yml.

This PR depends upon #1188.

I've introduced zod for this PR, with the intention that we'll slowly phase out simple-validators. There's a challenge with lazy inference and circular references detailed here: colinhacks/zod#3510

• Do not clobber existing myst.yml
• Upgrade glossaries
• Add unit tests

Closes #618

[stevejpurves]

Should we really begin phase out simple-validators? there is a significant cost in doing so...
and it's better to not to start a change on that scale unless we intend to follow through. Using zod in isolation for an upgrade command seems ok though, and a chance to see how it might be applied.

[agoose77]

@stevejpurves I agree. My suggestion is that we evaluate zod here, and look to make better use of it if it transpires that it's a good fit internally.

[choldgraf]

@agoose77 if the goal is to use this to learn about zod and whether it's a good idea for future adoption, I'd recommend:

• Opening an issue like 'evaluate the use of zod in the myst CLI' and link to the module where we've trialed it here
• Add the questions that you'd want to answer to decide whether it should be adopted more broadly
• Define a date by which you want to revisit the issue to make a decision
• Add a comment in the codebase that references that issue and notes the date to look at it

That way you can structure the information gathering rather than have it as a one-off tool that might confuse us in N months when we've forgotten about this conversation

[choldgraf]

One more recommendation here (or in a follow up pr if it's out of scope)

If we detect a config.yml file, I assume we want to note the upgrade command. But for a while, I think we should also note that people can run the v1 version of jupyter book by installing the version ==1. Alternatively what do you think about making a pypi package like jupyter-book-sphinx and pinning that to the 1.x series (similar to nbclassic)

[agoose77]

I tried this on CMIP6:

• toc was placed in the root indentation
• toc missed the README.
• We should be smarter about parsing author lists, e.g. things split with commas.

[agoose77]

@fwkoch your thoughts on this would be welcome. I've decided that instead of a myst upgrade command, this should just be myst init when we detect a Jupyter Book. This has some nice ergonomics, mainly

1. myst/myst --init directly upgrades un-ported Jupyter Books (nice short UX)
2. Repeated myst/myst --init does not, because myst.yml exists
3. myst upgrade is reserved for actual MyST-specific scoped upgrades

I tested the WIP on The Turing Way, and it seems to handle it fairly well.

[agoose77]

The line between "upgrading" a JB and upgrading MyST syntax is a little blurry. My take is that the JB upgrade is special, and we should treat it as such -- users will have an "old" project with known legacy aspects, vs users with one year old MyST projects that use some slightly deprecated syntax.

[agoose77]

I need some help setting up unit tests for this (I am hoping someone else will make my life easier...)!