search

jupyter-book / mystmd

Command line tools for working with MyST Markdown.
https://mystmd.org/guide
MIT License
219 stars 64 forks source link

Tracking: Turing Way #1336

Open rowanc1 opened 5 months ago

rowanc1 commented 5 months ago

We had a wonderful conversation this morning with the TuringWay team on how best to support the TuringWay team in their adoption of JupyterBook v2, which will be using mystmd. There were a lot of exciting possibilities that we talked about in terms of creating an ecosystem of content that the TuringWay could expose (figure, equations, glossaries), and that be included, linked to and cross-referenced by other books, tutorials, and communities in the wider open-science ecosystem. There are also some current deficiencies in MyST MD at the moment, one of the core ones is around internationalization. We got a really good demo from @BatoolMM on how that process is working, and some of the sticking points on how to bring content together to have a unified experience between languages. The localization also must include right-to-left languages, which will require a number of style updates and improvements across the components.

Resources for translations:

Example of Turing Way content deployed in MyST

Some cool things

image

turing-way-hover

Updates that need to happen

There are probably a number of other things that will come out as we work towards these goals, I encourage members of the TuringWay team to jump in here and let us know how we can support you. Please try the preview above and get a sense of where we are at. One of the cool wins is that the performance of navigating between pages should be improved quite a bit. There are also some abbreviations that will work and increase accessibility etc. for various pages.

I know that my team and @agoose77 do have some time to help with specific things, and some issues are in progress this week, so hopefully when we meet again in a few weeks there will be some progress to show!

@JimMadge @da5nsy @BatoolMM @agoose77 @sgibson91

We have had some previous conversations with the Environmental DataScience Book as well:

https://github.com/alan-turing-institute/environmental-ds-book

@acocac

da5nsy commented 5 months ago

Amazing, thank you so much for getting the ball rolling on this @rowanc1. Really excited to see where we can go with this. And happy to assist where we can!

Linking to the issue over on TTW where we've been tracking our own attempts/progress on enabling multi-language support: https://github.com/the-turing-way/the-turing-way/issues/3255

agoose77 commented 5 months ago

@rowanc1 was this meeting recorded in any fashion? I had some pre-conceived ideas around what TTW is doing regarding Crowdin, etc, and I know a bit about the space of tools. My read is that there are many ways to do this, so any guidance on the solution that TTW is converging on would be useful context.

da5nsy commented 5 months ago

Hi @agoose77! Not recorded I'm afraid, but I'm happy to answer (or redirect) any questions you have.

@BatoolMM is the person to ask about translation, or have a look here at our existing documentation.

And then from an infrastructure perspective this is the latest. In summary, there's currently no obvious out-of-the-box tools that we could use to deploy a multi-language site. We might be able to get something working with RTD, but honestly we would prefer an internal process that didn't rely on an external build service (so that we would be able to host anywhere). (@JimMadge, @sgibson91, @bsipocz - correct me if I've misunderstood!)

rowanc1 commented 5 months ago

@fwkoch just made a change that takes turing way from >1min to build to 17 seconds. 🚀

image

JimMadge commented 5 months ago

Just leaving some of my thoughts/opinions,

Hosting isn't the same as the build. However, hosting that we have considered/used (Netlify, RTD) do place restrictions on the build. Ideally, I would prefer that we control the build and just copy the output somewhere to host.

Multilingual support seems surprising difficult given how many languages are commonly used. A lot of the solutions we have looked at seem to have inherited the idea of translations from software, where you have either

Neither of these feel like they suit us. We don't want to enforce the idea of a primary or default language. We don't really see the task as reproducing the same information in each language.

Maybe we want something more like Wikipedia, where different languages are fairly independent but if there are pages on the same topic in two languages, you can switch between them.

This really isn't my area so I have no idea how difficult or possible that is :laughing:

da5nsy commented 1 week ago

Hi folks! Just adding a note to say that I tried following the instructions at https://next.jupyterbook.org/upgrade to test upgrading TTW and totally failed. https://github.com/the-turing-way/the-turing-way/pull/3958 Might be a Windows thing, or just me goofing something up, but I don't know.

agoose77 commented 1 week ago

@da5nsy thank you for trying out Jupyter Book and reporting back! I'll take a look at this within the next day.