Make execute_notebook: cache the default and deprecate auto?

[chrisjsewell]

I never use auto and I don't see the point in it.
Initially, I can see how jupyter-cache was more complex and more of unknown.
But now it is pretty well solidified, I have never found an issue with it, and we actually use it for building both the myst-nb and jupyter-book documentation.

Deprecating auto would allow us to better streamline our execution flow, and would minimise the choice and possible confusion for users.

@choldgraf @AakashGfude @mmcky etc, tell me why auto is so great 😜
(or what needs to be improved about cache to make it the one to rule them all)

[mmcky]

hey @chrisjsewell I have found having multiple options confusing.
I am in favour of make cache the one to rule them all.

[AakashGfude]

from my knowledge, stability was the primary reason. I think we can remove auto now 👍

[choldgraf]

tell me why auto is so great

The main reason is that IMO less complexity is (almost) always better than more complexity, and stable tools are (almost) always better than newer tools. But that decision was made about 5 months ago, so it's possible things have changed since then as @mmcky mentions.

I will leave it to you all to decide whether or not to deprecate auto, because I think you have more experience building books than I do, but I'll give you my personal decision criteria:

Which option is simpler for somebody that has never coded before except they've attended one bootcamp where they learned Jupyter notebooks? Which pattern is less likely to make this person confused or uncertain about what is going on? Which pattern is easier to explain to that person so they understand what is happening?

[chrisjsewell]

Which option is simpler for somebody that has never coded before except they've attended one bootcamp where they learned Jupyter notebooks? Which pattern is less likely to make this person confused or uncertain about what is going on? Which pattern is easier to explain to that person so they understand what is happening?

To all of these I'd answer cache: "the notebook will be re-executed when a change in the code is detected"

Personally I just don't think auto really works very well; for both MyST Mardown NBs, whereby you have to re-execute every time you change a word, and ipynb's where you presumably have to change the config to force every time you want to re-execute.

I think it could actually just be in the config execuction: on/off, and move the force to a CLI option

[choldgraf]

I guess the main thing I worry about is users seeing error messages that include references to SQLite and things like that. But again it's just been a while since I've used jupyter-cache directly so maybe all of this has been improved in the last few months. If it has then I am 👍 on just using execution: on because I agree it is simpler to have fewer choices than more. Also +1 on --force-execution at the CLI or something like this

[chrisjsewell]

users seeing error messages that include references to SQLite and things like that

In all my documentation builds of myst-nb and jupyter-book in the last month, I haven't once seen an error like this, or had any failings of jupyter-cache. But I'm sure issues will be raised if people do start encountering them for whatever reason.

In the next release of myst-nb then, I will look to add a deprecation warning for auto, encouraging the use of cache, and we can start from there.

While I'm at it, I will probably also deprecate jupyter_execute_notebooks, for something more obvious and aligned with the rest of the configuration names, like execution_method.
(addressing jupyter-book/jupyter-book#942)

[choldgraf]

sounds good

we may want to have a minor-version deprecation cycle or something like this, so that we can raise a warning for people to change their configs

[chrisjsewell]

Did you not read my last message lol, i.e. adding a deprecation warning

[choldgraf]

sorry, I was just referring to your last sentence about changing the config pattern

I will probably also deprecate jupyter_execute_notebooks

I didn't make the connection that the DW would apply to both. Go easy on me man I'm working on like 1-3 hours of sleep a night here

[chrisjsewell]

No excuse 😜😂

[mmcky]

@choldgraf I am amazed you can make any comments at all -- I am just in recovery 2 years latter :-)

[mmcky]

@chrisjsewell I like your plan. I think having cache as the default but have the option to clean build everything via the cli with --force-execution is nice.

An alternative is to setup an execute entry point for the cli to give a bit more control such as:

jb build <book> --execute="cache" (default option for cached execution of project)
jb build <book> --execute="off" (or False)
jb build <book> --execute="all" (or "clean")

with could override a _config.yml for special runs.

[akhmerov]

Making cache the default is great, especially helpful for non-expert users. An easy failure mode that I observed is having an irreproducible output by modifying cells out of order and forgetting to rerun all cells.

[choldgraf]

Did we reach a resolution on this one? I am fine making cache the default option instead of auto, provided that @chrisjsewell and others are confident that we won't significantly increase the odds that users see error messages that they don't know how to debug

[chrisjsewell]

well yes my resolution is cache, just got to find the time to do all the improvements/deprecation in myst-nb to make it a reality 😬 (it will happen eventually!)

[chrisjsewell]

with my CLI plugin system introduced in jupyter-book/jupyter-book#1293, I also want to look into pluggin in some/all of the jupter-cache CLI to jupyter-book, so that people maybe have the capability to execute individual notebooks outside of the book build

[mmcky]

I think cache is a good idea as the default. That would be my vote too.