search

spatialaudio / nbsphinx

:ledger: Sphinx source parser for Jupyter notebooks
https://nbsphinx.readthedocs.io/
MIT License
449 stars 128 forks source link

Unable to create gallery with notebooks out of the doc tree with nblinkgallery #749

Open gVallverdu opened 1 year ago

gVallverdu commented 1 year ago

Hi, I have a python project structured like this:

projects/
    - docs/
        source/
        conf.py
        index.rst
        ...
    - src/
        ...
    - notebooks/
        example.ipynb

In my documentation, I would like to include notebooks from the notebooks directory lying in the root directory of the project.

Following this example https://nbsphinx.readthedocs.io/en/typlog-theme/a-normal-rst-file.html#thumbnail-link-galleries-html-only, I tried to write something like this

.. nblinkgallery::
    :caption: A few links

    ../../../notebooks/example.ipynb

But the gallery appears empty. Only the caption is displayed on the html doc.

I got a warning like:

user_doc/index
/Users/gvallver/git/pyc2mc/docs/source/user_doc/index.rst:14: 
WARNING: la table des matières contient des références à des 
documents inexistants 'notebooks/example'

The html output is

<div class="toctree-wrapper compound">
<p class="caption" role="heading"><span class="caption-text">A few links</span></p>
<div class="nbsphinx-gallery">
</div>
</div>

In my conf.py I have

extensions = [
    "sphinx.ext.autodoc",  # automatic generation of doc
    "sphinx.ext.viewcode",  # link to code source in the doc
    "sphinx.ext.napoleon",  # doc format
    "nbsphinx",  # jupyter notebook support
]
sgbaird commented 1 year ago

I use PyScaffold to create templates gives me a folder structure similar to what's mentioned (i.e., a top-level notebooks folder), so this functionality is important to me.

The following is expected behavior:

WARNING: toctree contains reference to nonexisting document

One workaround is to use nbsphinx_link.

Thumbnails present a whole other set of issues: https://nbsphinx.readthedocs.io/en/0.9.2/subdir/gallery.html.

One option for local image files:

from IPython.display import Image
Image(filename="sdl-demo-test.jpg")

Related