Include notebooks from outside the root directory

[Olllom]

I have a directory tree like

my_project
    |- docs
         |- conf.py
         |- index.rst
         |- ... some notebooks ...
    |- examples
         |- ... some notebooks ...
    |- code

Is there a straightforward way to include the example notebooks into the toctree of my index.rst without copying them over to docs?

[Olllom]

At the moment, I am using a workaround in my conf.py.

print("Copy example notebooks into docs/_examples")

def all_but_ipynb(dir, contents):
    result = []
    for c in contents:
        if os.path.isfile(os.path.join(dir,c)) and (not c.endswith(".ipynb")):
            result += [c]
    return result


shutil.rmtree(os.path.join(project_root, "docs/_examples"), ignore_errors=True)
shutil.copytree(os.path.join(project_root, "examples"),
                os.path.join(project_root, "docs/_examples"),
                ignore=all_but_ipynb)

... this works, but does not seem quite right.

[mgeier]

This is not directly supported in nbsphinx, see discussions in #33.
I've actually suggested your work-around in #33 (comment).

As an alternative, you can try https://github.com/vidartf/nbsphinx-include

My favorite option is indeed moving the notebooks to the docs/ folder and creating a symbolic link back to wherever else they should appear.
Note, however, that it doesn't work in the other direction yet, see #49.

If you have another idea how to handle this, I'm open for suggestions!

[Olllom]

Thank you.
I will stick with the workaround mentioned above.

[Vital-Fernandez]

Hello @Olllom , @kolibril13. At the present day you still recommend copying the files?

[kolibril13]

Currently, I am mostly using JupyterLite builds to publish my notebooks.
I copy extra content (e.g. readme files) via github actions into the right folder.
https://github.com/widgetti/ipyreact/blob/a86b6d9e5f5b4e1501722bcd1ca3e08dcb025368/.github/workflows/deploy.yml#L24-L27
Hope that helps!