Support notebooks outside of Sphinx root directory.

[jklaise]

I'm currently using nbsphinx to convert example notebooks to static documentation and they have a nifty plugin nbsphinx-link which allows the notebooks to reside outside the sphinx root directory. This is useful because then the example notebooks can live at the top level of a code repository (examples), whilst the documentation under doc/source can still include the examples directory in the doc files to be built (nbsphinx-link achieves this by creating .nblink files under doc/source which contain relative links to the source notebooks).

I've had a look at the myst-nb and myst-parser documentation and I saw the section on including files but not for linking to files outside of sphinx root. Is this something that is supported or planned? Thanks!

[welcome]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.

If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).

Welcome to the EBP community! 🎉

[chrisjsewell]

hey @jklaise thanks for the link, its not something I had heard of before. I will try to check it out soon, to see how it is implemented.
This was not specifically in the plans, but if it is something that is not too difficult I would certainly be interested

[ma-sadeghi]

We're also in the same boat, we're using nbsphinx alongside nbsphinx-link to circumvent the issue. But, we'd like to migrate to myst-nb, but that's kind of a roadblock. As a workaround, I guess we could just copy the entire examples folder to the sphinx root folder inside the GitHub Action that generates the documentation, but it'd be nice if mynb-st could support that right out of the box. Thank you so much!

@chrisjsewell Any updates by any chance? Thanks!

[fmfreeze]

Decoupling the docs folder with it's sphinx scripts from (jupyter notebook-)source files would be awesome.
That would enable a smooth transition from real production notebooks (for broader usage) into docs integration.

[ma-sadeghi]

We eventually migrated to myst-nb, and for now, we're copying the "examples" folder from the root directory to docs as part of the GitHub Action that generates our documentation. So, it's all good, but still it'd be nice if it could support rendering notebooks in arbitrary paths.

[chrisjsewell]

It'd be nice if mynb-st could support that right out of the box

So, my opinion is that this is not something that myst-nb should support specifically... because myst-nb just providers a parser to sphinx to treat notebooks the same as any other source file, such as .rst or .md files.

It's a stipulation of sphinx, that source files reside in a certain folder, and so I feel the solution here is just more general for sphinx, and should either be "fixed" upstream or by another extension, that would cover not just notebooks but all source files.
You could probably just extract the code from nbsphinx-link and make it into a more generic sphinx extension?

Optionally, if you want the "whole" of your repository to potentially include source documents, why not just set sphinx to read from the whole repo (rather than specifically a doc/source folder), and then specifically set any https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-exclude_patterns?
Indeed many jupyter books, which is just a thin wrapper around sphinx+myst-nb, are built from the root of the repository (https://executablebooks.org/en/latest/gallery.html)

[fmfreeze]

I understand your argument @chrisjsewell

why not just set sphinx to read from the whole repo (rather than specifically a doc/source folder)

I am aware of exclude_pattern but how do I set Sphinx' "root"?

I don't want to move Sphinx' conf.py and index.md into the repositories root, which would be a way I could think of how to do it.

[chrisjsewell]

This may be of note: https://github.com/useblocks/sphinx-collections