Executable docs option with Jupyterbook?

[lsetiawan]

As of late, I've found myself building documentation with Jupyterbook for a scientific python package I'm helping build called echopype. Jupyterbook is built on top of sphinx so I get the same configurations and extensions as sphinx but also the power of the Jupyter ecosystem. I am now able to put both examples and API docs in the same place since Jupyterbook can render so many various files. Since we are in the scientific python space, maybe having an option to use Jupyterbook for docs would be really cool to have! Let me know what you all think! 😄 Thanks!

[henryiii]

See #157. For a Python package, I'd use nbsphinx, which also supports setting a kernel (IIRC still missing from Juptyerbook), and lets you stay in the normal sphinx themes, readthedocs, and such. (I do use jupyterbook a lot, just not for package documentation, and the components developed for it are used already, like myst).

I do think we should list it as an option, though, along with mkdocs; I hadn't seen it used as the entire package docs before.

[danielballan]

I am supportive of this. Some thoughts on how to include it…

When the Jupyter ecosystem was just beginning to develop, the way to do executable docs was the IPython sphinx extension, mentioned in #157. Now I believe the simplest way to achieve something similar, and a little more robust, is Jupytext.

One goal of this guide is to address people whose primarily job is science, not software, and to avoid bewildering them with too many choices or technologies up front. With that in mind, I might be inclined to first show Jupytext as the simplest escalation from "minimal sphinx" to "and now I want to execute some code" and then either mention Jupyter Book and link out to it, or address in a second topical guide.

[danielballan]

Ah, @henryiii’s reply landed while I was composing mine. Seems like we are thinking along similar lines.

[lsetiawan]

Thanks @danielballan and @henryiii for your thoughtful response! I was not aware of these other tools, though I've heard of mkdocs.

One goal of this guide is to address people whose primarily job is science, not software, and to avoid bewildering them with too many choices or technologies up front

I totally agree that we don't want to overwhelm scientists with all of these technologies up front. I think finding a technology that is simplest to get started is key here. And probably making aware of these other options would be great. Jupyterbook is a very opinionated flavor of sphinx and it does work on readthedocs as well as demonstrated on my initial comment.