elaborate on the relationship with readthedocs or related plans

[parmentelat]

Is your feature request related to a problem? Please describe. I come from using ipypublish to create sites on readthedocs.io from git repos that essentially act as binders of notebook-based courses, and I am giving jupyter book a try as a ng replacement

however I could not find any mention of readthedocs.io in the doc https://beta.jupyterbook.org/search.html?q=readthedocs#

I tried to figure out some of it by myself but to no avail; my first throw-away sandbox has no conf.py file, although there clearly is an underlying sphinx running under the hood; my - admittedly shallow - understanding was that this conf.py thing was acting as some sort of a trigger in the github/readthedocs.io integration pipeline

Describe the solution you'd like

all this being said I perfectly understand if that was not a short-term objective if the project is in a early phase

it would help IMHO if the docs could address that specific area
one easy way could be to simply state what the status currently is and what the plans are

also maybe elaborate on the reason why beta.jupyterbook.org does not run under readthedocs ? is this precisely b/c it's not possible yet, or b/c you prefer it that way ?

hope this helps :)

[choldgraf]

@parmentelat this is definitely helpful, thanks for bringing it up. We've discussed it before and is something we'd really like to support. One of the reasons to move to Sphinx was to more easily connect with the readthedocs community. We've also spoken a bit with @ericholscher but haven't yet come to a conclusion for how jupyter book could be built within RTD

The challenge is that readthedocs is optimized for vanilla Sphinx sites (e.g. it hard-codes sphinx commands that it runs to build docs). Jupyter Book is nearly this, but it doesn't use standard Sphinx commands to build (rather, it uses jupyter-book build)

So I think there are two ways that it could be accomplished, but they'd take a bit of thinking / dev:

1. Find a way to make jupyter book output a "traditional" sphinx site that could be built.
2. Find a way for readthedocs to support building jupyter books (I'm not sure whether RTD supports custom build commands right now)

[ericholscher]

We are definitely interested in supporting it. The easiest option for sure would be to run it via a normal Sphinx conf.py. There are ways we could hack this, but I think adding a custom build command (or even just a special case for jupyter-book for now) would be 👍 on our side.

[choldgraf]

That's great to hear :-) in case it's useful, here is what the build CLI option does:

https://github.com/ExecutableBookProject/cli/blob/master/jupyter_book/commands/init.py#L36

basically, it's just setting up some configuration options etc and then calling a sphinx build that is almost copy-pasted from Sphinx itself (https://github.com/ExecutableBookProject/cli/blob/785d7a541d225bd22eaa3e977b8b8705d7341856/jupyter_book/sphinx.py#L42)