Support for Jupyter-Book

[jonathf]

What would you like to see

I am using Jupyter-Book as a Sphinx wrapper. It would be awesome to see Esbonio support this format as well as native Sphinx.

When I open an RST-file in a Jupyter-Book project now, I get an error that it can not find the file conf.py.

The differences between Sphinx and Jupyter-Book is minor:

• Sphinx uses conf.py and index.rst for configuration, while Jupyter-Book uses _config.yml and _toc.yml.
• The build tools are sphinx-build and jupyter-book build, but they support the same functionality
• Jupyter-Book installs a few extra plugins by default, like MyST.

[alcarney]

How interesting!

I'd definitely like to see this happen however, I'm not going to be looking at this any time soon, certainly not before the 1.0 release is out. So if someone else wants to take this on please do! I'd be happy to help them figure out the details.

I should also say I'm (probably) not going to accept jupyter-book specific code to support this into Esbonio itself.

The rule of thumb I've been working to is,

• if it comes in Sphinx itself, Esbonio should support it
• if it's not in Sphinx, Esbonio should be extensible enough so that it's possible for a 3rd party to provide that support.

(It's probably time I had that written down somewhere! :sweat_smile:)

Below are some random thoughts I had while looking into this

---

The differences between Sphinx and Jupyter-Book is minor

Unfortunately.... it might still be different enough to make adding support non-trivial :/

Esbonio does not actually use the sphinx-build cli to control Sphinx, it instead imports Sphinx as a library, overrides/extends a bunch of things and runs the build itself in a long running process.

It looks like jupyter-book build does some of that as well, so I'm not sure what it would take to get the two to play nice with each other... :thinking:

However, reading this section of their docs, perhaps it would be possible to write a config export tool to make a jupyter book project "look right" to Esbonio? (This is probably the easiest, but clunky option to get something going in the short term)

If ultimately, the differences are just configuration then it would be possible to have some kind of "middleware" component do the translation and generate the corresponding configuration Esbonio can send across to its sphinx process (would require #785)

[jonathf]

Interesting. Thanks for looking into it. And thanks for the explaination. It has been interesting to see how you guys interact with Sphinx.

Yeah, and middleware of some sort might be enough if there isn't any parameters or patching that are in conflict. I would take a look at it myself, but I enough on my plate for such a project right now.