Notebook gallery with thumbnail links only

[adonath]

We use the .. nbgallery:: directive in the documentation of the Gammapy project to include tutorial notebooks in the normal documentation (https://docs.gammapy.org/0.20.1/tutorials/index.html). This feature works great and adds a lot of value and improved accessibility to the documentation. Thanks for this!

The way .. nbgallery:: is implemented it works as a toctree. I think it would be a nice feature to be able to have the nbgallery work as links with thumbnails only. The use case we have in our documentation is to be able to link to tutorials using thumbnails from e.g. the user guide:

• https://docs.gammapy.org/0.20.1/user-guide/dl3.html#using-gammapy-data
• https://docs.gammapy.org/0.20.1/user-guide/maps/index.html#using-gammapy-maps

We already do this, however it leads to a broken navbar structure (https://github.com/gammapy/gammapy/issues/3985), because rendered tutorials are part of multiple toctree structures. This makes the content of the left sidebar dependent on the order the pages are being rendered. One way to resolved this issue for us would be to have a nbgallery directive, which does not act as a toctree but just as plain links. Is any feature like this planned? How could it be implemented most easily?

Issue #647 might be related, but has different motivation.

[mgeier]

Thanks for bringing this up!

Is any feature like this planned?

It's not planned, but I think it would be a very good idea!

How could it be implemented most easily?

I don't know. I think a separate directive (something like nblinkgallerymaybe?) would have to be implemented. The entries would have to be looked up in the known source files to check if they exist. I'm not sure how globbing would work, but maybe this doesn't have to be implemented at first. Then, given the list of source files, the appropriate docutils nodes would have to be created.

I currently don't have time to look into this, but if you need help, please let me know!

[adonath]

Thanks @mgeier for the response! I'm actually interested to work in this, however I have minimal knowledge on implementing sphinx extensions.

The first part on parsing and checking the source files should be fine. But I'm not sure what the correct docutils nodes are to represent the structure. Looking at an example html from the Gammapy documentation:

<div class="sphx-glr-thumbcontainer" tooltip="Data inspection and preliminary analysis with Fermi-LAT data.">
  <div class="figure align-center">
    <img alt="thumbnail" src="../_images/tutorials_data_fermi_lat_54_0.png" />
    <p class="caption">
      <span class="caption-text">
        <a class="reference internal" href="../tutorials/data/fermi_lat.html">
          <span class="std std-ref">Fermi-LAT with Gammapy</span>
        </a>
      </span>
    </p>
  </div>
</div>

I would need the link to the thumbnail png, the title and optionally the tooltip of the notebook. Extracting or creating all this information by hand does not make sense to me, so there must be some sphinx-gallery "magic" behind (some custom nodes?), which I should re-use. Do you have any advice on this? Thanks!

[mgeier]

There is already a GalleryNode which I think you could re-use. It should automatically create the relevant HTML code. You only have to specify entries, which is a tuple of (title, uri, filename, tooltip). You should be able to get this information from app.env.nbsphinx_thumbnails.get(doc, {}). The important part is to query this information at the correct time, i.e. after all notebooks are parsed. Currently, this is done in the doctree-resolved event.

So I think you should maybe create a placeholder node similar to GalleryToc (maybe GalleryLinks?) which contains the source names that you have parsed from the notebooks. Then, in doctree_resolved(), you can replace your placeholder nodes with GalleryNode nodes and set the correct entries.

Does that sound reasonable?

[adonath]

Thanks a lot @mgeier, this sounds doable! I might come up with a first implementation next week...