Convert to jupyter-book
Jupyter book is a powerful, but still developing set of tools for publishing notes with flexible system, sufficient options for customization of markup, and a lot more. I am certain that switching to use jupyterbook will be a big improvement.
That said, there are still important limitations that prevent an immediate switch or require manual work. I will update this list as needed.
-
There needs to be a way to hide all executed code by default. -
We make heavy use of admonitions, including collapsible ones. jupyter-book realizes these either via sphinx-panels
extension, or sphinx-togglebutton. We'd need to:- Decide which one is better.
- Figure out how to introduce clear syntax that suits our needs (the full syntax may be too low level)
-
Binder and interaction buttons implemented in sphinx book theme doesn't support gitlab. While this amounts to fixing some URLs to make these work with gitlab, it's still some work. -
Sometimes we are using <abbr>
terms, need to check if these work
In addition to these basic features, it would be good to move learning goals and prerequisites into metadata of each page. That would require writing a sphinx extension.