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

**URL:** <https://discourse.jupyter.org/t/migrate-from-sphinx-to-jupyterbook-deal-with-dead-urls-and-localization/6341>\
**Category:** General\
**Created:** [October 13, 2020, 2:42pm UTC](https://discourse.jupyter.org/t/migrate-from-sphinx-to-jupyterbook-deal-with-dead-urls-and-localization/6341 "2020-10-13T14:42:58Z")\
**Posts on this page:** 8\
**Page:** 1

<div class="post-metadata">

**Author:** ![fmaussion](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.jupyter.org/fmaussion/32/390_2.png) [@fmaussion](https://discourse.jupyter.org/u/fmaussion)\
**Post date:** [October 13, 2020, 2:42pm UTC](https://discourse.jupyter.org/t/migrate-from-sphinx-to-jupyterbook-deal-with-dead-urls-and-localization/6341/1 "2020-10-13T14:42:58Z")

</div>

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

Hi! I’m thinking about migrating [https://edu.oggm.org](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](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](https://edu.oggm.org) is technically available in other languages already. Does jupyterbook support localization like [readthedocs](https://docs.readthedocs.io/en/stable/localization.html) does?

Thanks!

---

<div class="post-metadata">

**Author:** ![sgibson91](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.jupyter.org/sgibson91/32/487_2.png) [@sgibson91](https://discourse.jupyter.org/u/sgibson91)\
**Post date:** [October 13, 2020, 4:14pm UTC](https://discourse.jupyter.org/t/migrate-from-sphinx-to-jupyterbook-deal-with-dead-urls-and-localization/6341/2 "2020-10-13T16:14:46Z")

</div>

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](https://github.com/alan-turing-institute/the-turing-way)  
Gitter: [https://gitter.im/alan-turing-institute/the-turing-way](https://gitter.im/alan-turing-institute/the-turing-way)  
Slack: [https://tinyurl.com/jointuringwayslack](https://tinyurl.com/jointuringwayslack)

Otherwise, I think the Jupyter Book forum is: [discuss.executablebooks.org](http://discuss.executablebooks.org)

---

<div class="post-metadata">

**Author:** ![fmaussion](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.jupyter.org/fmaussion/32/390_2.png) [@fmaussion](https://discourse.jupyter.org/u/fmaussion)\
**Post date:** [October 13, 2020, 4:29pm UTC](https://discourse.jupyter.org/t/migrate-from-sphinx-to-jupyterbook-deal-with-dead-urls-and-localization/6341/3 "2020-10-13T16:29:12Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![fmaussion](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.jupyter.org/fmaussion/32/390_2.png) [@fmaussion](https://discourse.jupyter.org/u/fmaussion)\
**Post date:** [October 13, 2020, 4:31pm UTC](https://discourse.jupyter.org/t/migrate-from-sphinx-to-jupyterbook-deal-with-dead-urls-and-localization/6341/4 "2020-10-13T16:31:21Z")

</div>

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

The localization I’m not sure yet.

---

<div class="post-metadata">

**Author:** ![mgeier](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.jupyter.org/mgeier/32/1192_2.png) [@mgeier](https://discourse.jupyter.org/u/mgeier)\
**Post date:** [October 19, 2020, 2:35pm UTC](https://discourse.jupyter.org/t/migrate-from-sphinx-to-jupyterbook-deal-with-dead-urls-and-localization/6341/5 "2020-10-19T14:35:06Z")

</div>

> [@fmaussion](#):
>
> I’m thinking about migrating [https://edu.oggm.org](https://edu.oggm.org) from sphinx+readthedocs to JupyterBook+ghpages.

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.

---

<div class="post-metadata">

**Author:** ![fmaussion](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.jupyter.org/fmaussion/32/390_2.png) [@fmaussion](https://discourse.jupyter.org/u/fmaussion)\
**Post date:** [October 19, 2020, 3:22pm UTC](https://discourse.jupyter.org/t/migrate-from-sphinx-to-jupyterbook-deal-with-dead-urls-and-localization/6341/6 "2020-10-19T15:22:51Z")

</div>

> [@mgeier](#):
>
> 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?

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?

---

<div class="post-metadata">

**Author:** ![mgeier](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.jupyter.org/mgeier/32/1192_2.png) [@mgeier](https://discourse.jupyter.org/u/mgeier)\
**Post date:** [October 19, 2020, 5:18pm UTC](https://discourse.jupyter.org/t/migrate-from-sphinx-to-jupyterbook-deal-with-dead-urls-and-localization/6341/7 "2020-10-19T17:18:24Z")

</div>

> [@fmaussion](#):
>
> I like the style of juptyter book (although I guess I could just switch to Sphinx Book Theme for that)

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/](https://insipid-sphinx-theme.readthedocs.io/)

> [@fmaussion](#):
>
> 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.

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](https://myst-nb.readthedocs.io/en/latest/), 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](https://nbsphinx.readthedocs.io/en/latest/).

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

> [@fmaussion](#):
>
> I also really enjoy the automated stuff like the automatic links to mybinder

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

- **docs** : [Prolog and Epilog — nbsphinx version 0.9.3-5-g3bc9d54](https://nbsphinx.readthedocs.io/en/latest/prolog-and-epilog.html)
- **example** : any page of the `nbsphinx` docs with a “launch binder” icon at the top, e.g. [Code Cells — nbsphinx version 0.9.3-5-g3bc9d54](https://nbsphinx.readthedocs.io/en/latest/code-cells.html)

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

> [@fmaussion](#):
>
> 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…

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!

---

<div class="post-metadata">

**Author:** ![fmaussion](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.jupyter.org/fmaussion/32/390_2.png) [@fmaussion](https://discourse.jupyter.org/u/fmaussion)\
**Post date:** [October 21, 2020, 8:09pm UTC](https://discourse.jupyter.org/t/migrate-from-sphinx-to-jupyterbook-deal-with-dead-urls-and-localization/6341/8 "2020-10-21T20:09:45Z")

</div>

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).