Adapting furo for jupyter-book

[alexisthual]

I think jupyter-book is a great library to easily organise a series of notebooks into a user-friendly website.

I just tried generating one such jupyter-book using furo. While the generated site looks okayish, a lot of important features of jupyter-books are missing, which I think is caused by the fact that furo doesn't handle theme options that jupyter-book expects to find:

WARNING: unsupported theme option 'search_bar_text' given
WARNING: unsupported theme option 'launch_buttons' given
WARNING: unsupported theme option 'path_to_docs' given
WARNING: unsupported theme option 'repository_url' given
WARNING: unsupported theme option 'repository_branch' given
WARNING: unsupported theme option 'google_analytics_id' given
WARNING: unsupported theme option 'extra_navbar' given
WARNING: unsupported theme option 'extra_footer' given
WARNING: unsupported theme option 'home_page_in_toc' given
WARNING: unsupported theme option 'use_repository_button' given
WARNING: unsupported theme option 'use_edit_page_button' given
WARNING: unsupported theme option 'use_issues_button' given

In particular, the navbar containing buttons to download the current notebook is not there.

Moreover, the look and feel of generated pages is not really furo-like. For instance, code blocks generally look greenish from another theme.

I think it'd be interesting to add features to furo so that it becomes compatible with jupyter-book, what do you think? 😊

[pradyunsg]

To answer the question: Yes, I think it'd be interesting to make changes on Furo's end for a better jupyter-book story. Now, let me elaborate on the caveats around that. :)

I've said this elsewhere -- the vague intent with Furo is to be really good with the 80%, and leave covering the 20% to other more... generously scoped projects. That leads to the general idea that Furo should not have too many knobs.

For example, Furo's configuration options are intentionally really light -- the intent is for Furo to not try and cover every usecase (that's very different from both pydata-sphinx-theme and sphinx-book-theme). This includes the omission of a top bar -- adding a navbar means an additional layer of configurability and user-extension point, which I definitely see value in, but isn't what I want Furo to try and cover.

The default configuration for jupyter-book is highly coupled/tied to https://github.com/executablebooks/sphinx-book-theme/. And, per above, the knobs that Sphinx Book Theme provides are not gonna map 1:1 to Furo and some of them will be missing with no intent to add them. :)

That said, I do think there's actionable bits here that I'll try to list in a follow up comment.

[pradyunsg]

Could you share a sample repository and instructions for how to build a jupyter-book site with Furo? I don't have much hands-on experience with jupyter-book, and having something working would be useful to figure out what the status quo is. 😅

(thanks for the screenshot though -- that gets me most of the way in getting a sense of what the issues are!)

[alexisthual]

Sure! So after having installed jupyter-book and furo in a python env, you can simply run jupyter-book create jupyter-book-furo.

Then, in ./jupyter-book-furo/config.yml, simply add the following lines:

sphinx:
  config:
    html_theme: furo

and run cd jupyter-book-furo & jupyter-book build .

You can find some useful instructions in jupyter-book's example on how to build a template book and in the subsection of advanced examples concerning custom themes.

[pradyunsg]

Here's the bits that I can already see here that are actionable:

• Adding functionality to allow documentation authors to add launch-in-binder/download buttons to the top-of-document icons that Furo has (along with actually making them sticky) will get us most of the way there. This is already a WIP thing for view/edit buttons beside the light/dark mode color toggle.
• I'm like... 80% sure somewhere in jupyter-book, the pygments theme is set to sphinx (search for style or pygments in conf.py or whatever the configuration file is -- or its defaults). That's the source of the incompatible colours (it overrides Furo's defaults).
• I'm not aware of which Sphinx extensions are enabled by default in jupyter-book. I'm open to exploring having better styles for them in Furo.

[alexisthual]

Indeed, I was able to change the highlighting style with:

sphinx:
  config:
    pygments_style: sas

Moreover, one can add custom CSS in ./static/custom.css and include this file with

sphinx:
  config:
    html_css_files:
      - custom.css
    html_static_path:
      - _static