Migrate from Sphinx to JupyterBook: deal with dead urls and localization

General
1

[NB: no tag or topic for JupyterBook? Am I in the right place here?]

Hi! I’m thinking about migrating https://edu.oggm.org from sphinx+readthedocs to JupyterBook+ghpages.

I have two questions which I hope are not too trivial:

  1. I’d like some of the widely shared links to redirect to the new jupyterbook equivalents. E.g. https://edu.oggm.org/en/latest/explorer.html -> whatever jupyterbook chose instead. I think I’ll have to fiddle around manually in the _build html files to do that, right? But it won’t be a problem or really difficult, will it?
  2. I really like the multilingual capability of sphinx - although we haven’t translated much of it yet, https://edu.oggm.org is technically available in other languages already. Does jupyterbook support localization like readthedocs does?

Thanks!

2

Hi! I wonder if it would be useful to connect with The Turing Way community? We had to handle some redirects and are also trying to provide multiple translations of the content as well. All built with Jupyter Book, though we publish with Netlify rather than GitHub Pages.

GitHub: https://github.com/alan-turing-institute/the-turing-way
Gitter: https://gitter.im/alan-turing-institute/the-turing-way
Slack: https://tinyurl.com/jointuringwayslack

Otherwise, I think the Jupyter Book forum is: discuss.executablebooks.org

1 Like
3

Thanks so much for the hints! I’ll definitely connect with both communities.

1 Like
4

For example the redirect question already has an answer: https://github.com/executablebooks/meta/discussions/117

The localization I’m not sure yet.

1 Like
5

Just out of curiosity: Would you be willing to share some of the reasons for changing?
What are you missing on Sphinx+RTD that’s there on JupyterBook+ghpages?

BTW, the newest generation of JupyterBook also uses Sphinx, but I guess that’s an implementation detail.

6

Thanks for asking! Main reasons:

  • I like the style of juptyter book (although I guess I could just switch to Sphinx Book Theme for that)
  • We’d like to use jupyter notebooks as content as well. Although I assume that there are sphinx tools for that, jupyter-book is just so… easy and seamless. I also really enjoy the automated stuff like the automatic links to mybinder
  • Our notebooks (which are currently only linked as “tutorials”, i.e. not rendered) need to run on rather complex python environments: I find it a real pain that we can’t use containers on RDT, and need to reinstall the 20+ packages via conda each time we will build the docs. With our own CI + ghpages we can use our containerized envs and resources to actually build the website instead of relying on RTD for the build…

I hope that makes sense?

7

Exactly! And if you stay with “plain” Sphinx, you can try other themes, while with Jupyter Book you are locked-in to a fixed theme (AFAIK).

For example, you could try the Sphinx theme I’ve created very recently (with a “book” use case in mind): https://insipid-sphinx-theme.readthedocs.io/

OK, I don’t know how seamless it is exactly, but using a Sphinx extension isn’t typically that hard either. And often it’s more flexible.

You could use Overview, which I think is what Jupyter Book uses internally (but you don’t need to actually use Jupyter Book).

But again, there are alternatives, you could also use my own Jupyter Notebook Tools for Sphinx — nbsphinx version 0.9.3-5-g3bc9d54.

Both have their advantages and disadvantages, but if you use “plain” Sphinx, you have the freedom to choose either.

They are probably not as automatic as those Jupyter Book links, but you can create similar links with nbsphinx:

The advantage here is that you are not limited to Binder links, you can link to anything you want in any way you want.

OK, that’s a really good point.

But this really doesn’t have anything to do with Jupyter Book, it’s all about RTD vs ghpages.

Installing stuff with conda on RTD can take a really long time, and the total runtime of your build is limited (last time I checked it was 15 minutes for non-paying accounts), so it might not be feasible.

But even if you switch to ghpages (which seems to make a lot of sense), you can still decide to use “plain” Sphinx.

Running Sphinx on CI and pushing the generated HTML files to ghpages should be trivial, but I guess it would be very nice to have multiple versions/languages there, which is for sure far from trivial. Sadly, I don’t know of a solution for that, I hope you’ll find something!

8

Thanks for all the tips! After giving it some thought, I think we’ll migrate the notebook only part to a jupyter-book page and leave the rest as is (maybe with some efforts to make the site look a bit nicer).