Jupyter-book: Only build files that are explicitly listed in _toc.yml

[akhmerov]

Is your feature request related to a problem? Please describe.

Specifying exclude_patterns = ["*"] would be a nice way to ignore all temporary files hanging around, except this also excludes the files explicitly listed in the toc.

Describe the solution you'd like

Change the behavior of exclude_patterns to not apply to files explicitly listed in the toc.

[choldgraf]

~yeah that's a good idea - I guess we could do something like add a list of */{path-to-pfile}* for each page in toc.yml?~

A quick update with how I think this could be fixed:

How to fix this

The tricky thing we'll have to deal with is that Sphinx automatically builds all files unless they are listed in an exclude_patterns config variable. So, I think that the way we'd wanna fix this could be:

• Triggered with a configuration value in _config.yml. Maybe only_build_toc_files: true or something.
• Glob all of the files in the book folder
• Loop through the _toc.yml and remove all of the files
• When we create the Sphinx config for a build (somewhere around here https://github.com/executablebooks/jupyter-book/blob/master/jupyter_book/config.py#L103), add in config["exclude_patterns"] += globbed_files_minus_toc_files.

And I think this should work. I'm happy to review PRs + tests that give this a shot!

[akhmerov]

Yes. Why the initial * in */{path-to-pfile}*? Speaking about that final asterisk: how does jupyter book interpret multiple files with the same name but different file extensions?

[choldgraf]

I dunno, I've just found exclude_patterns to be finnicky so I put asterisks all over the place haha

re your second question: only one of the pages will be build, I think that .md takes precedence over ipynb but I could be wrong and this should be documented (maybe another issue for it?)

[akhmerov]

Done: #682

[jni]

Just ran into this behaviour myself. I might even say that exclude_files=* while including the files in the toc should be the default behaviour. If I write out a toc explicitly, my own personal expectation is that that is the complete directory of the book contents and everything else in the repo has nothing to do with the book and should be ignored.

[AllenDowney]

I've just been bitten by this as well. I agree with the suggestion that the default should be to build only files listed in the toc.

More generally, I am having a hard time getting started because my use case is different from what's in the docs. I am starting with an existing repo that is full of material, and now I want to make a subset of it into a book. I'm finding it challenging to figure out how to do that because the tutorial is based on an example that starts with an empty repo.

[choldgraf]

I agree this would be a good feature to add, at least as a config option. I've updated my comment above with steps that I think would fix this, I'm happy to review PRs from folks that wanna give it a shot:

https://github.com/executablebooks/jupyter-book/issues/667#issuecomment-637637916

(I likely will not have time to work on it directly as I'm on paternity leave)

Also just a note to 👍 the top comment if you wish for it to be fixed

[alex-treebeard]

Joining the party...will take a look at a PR for this next week :)

[choldgraf]

closed by https://github.com/executablebooks/jupyter-book/pull/1123! thanks @alex-treebeard

[jni]

Whoo!!! 🎉 🙏