Jupyter-book: CLI: `page` command building/executing all notebooks

[rossbar]

There appears to be an issue with the jupyter-book page command. In principle, page is supposed to convert the given source file into HTML (or pdf, given the option). However, it seems that jb page <file> will actually trigger the execution of the notebooks that are in the same directory.

This can be reproduced with the basic juypter-book example:

jb create spam
cd spam
jb page intro.md

Note that there are two issues here, probably interrelated - 1) page is only supposed to work on a single page rather than the entire book and 2) the default value for executing the books is off, so jb page file should not try to execute the file (if it is a notebook or myst-nb text-formatted notebook).

jupyter-book version: 619e33f2d

[choldgraf]

I think that's probably a bug somewhere around here: https://github.com/executablebooks/jupyter-book/blob/master/jupyter_book/commands/__init__.py#L225

we are trying to grab all files except the one listed and telling Sphinx to ignore it, but for some reason this doesn't seem to happen. Maybe the info for a fix could be found here: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-exclude_patterns

?

[rossbar]

Yeah I had seen the same thing - sorry I don't mean to be bombarding with issues and not helping solve anything! I'm trying to chase down a problem with building Elegant Scipy with the new jb toolchain and reporting ancillary things I'm finding as I'm chasing down this issue.

[choldgraf]

oh please do keep reporting, it is super helpful :-)

[choldgraf]

ok I think I fixed it here: https://github.com/executablebooks/jupyter-book/pull/592

[rossbar]

Yup, it looks like #592 handles the single-page execution correctly. There still is a bit of weirdness with the --execute cli option: From the code, it seems like the default should be to not execute the page:

https://github.com/executablebooks/jupyter-book/blob/4ed6e87bb93c001674f87eef37a83fe0b79fc20d/jupyter_book/commands/__init__.py#L212-L235

But in practice it seems to execute no matter what option is passed in for --execute. This is probably a separate issue though (or maybe I'm missing something).

[choldgraf]

ah that might be copy-pasta? my intuition is that the default should be to execute if it's a single page. So the flag should be --no-execute IMo. What do you think?

[rossbar]

I'm used to notedown which has the opposite default (i.e. don't execute be default) but in the context of book-building I think you're right that executing the notebooks should be the default.

Either way, IMO it would be nice if it were a binary flag rather than an option that takes a text argument for one of the "execute" configuration options ("auto", "cached", etc.). I think the binary behavior is more in line with what a user would expect when building a single page.

[choldgraf]

yeah - I agree w/ that. Wanna make a PR to change it to --no-execute as a flag? If people want the execution to be cached in the future we can always add a --cache flag as well.

[rossbar]

I'll aim to address it this evening :)

[rossbar]

It looks like the change might be a bit more involved than I had originally thought - it seems myst-nb might be running the notebooks even when configured not to. I'll have to take a closer look...

[choldgraf]

Hmm, if you set execute to off then it shouldn't execute anything. Did you try that? Feel free to open a PR we can iterate on

[rossbar]

Yeah the jupyter_execute_notebooks value wasn't making it from the config dictionary through to the myst-nb parser. Based on your changes in #592, I was able to trace the problem back to jupyter_book/yaml.py. I'm still not 100% on the actual mechanics of what is happening, but it seems like the values from the sphinx.config.Config object that is passed into yaml_to_sphinx (at whatever point that's getting called) are not generally being added to the sphinx_config dict that is then passed along.

I just now think I've landed on a potential solution (specific to the jupyter_execute_notebooks config value) and will PR shortly, but based on this fix and changes in #592 , it seems like there may be a more general problem with config values not being passed through the entire build chain intact.

[choldgraf]

ah that is helpful to hear, thanks, I'm still not happy with how configuration is handled under-the-hood...it feels a bit hacky as you have probably noticed :-) looking forward to the PR!