Referencing notebooks from .rst files (sphinx build)

HoloViews
1

Hello!
I’m trying to use the same paradigm for referencing notebooks during the sphinx-build as you:
In your main index.rst, you reference the getting started index. Here, you reference , among others, the Live Data notebook.
For referencing you use the following syntax:

.. notebook:: holoviews ../../examples/getting_started/5-Live_Data.ipynb
    :skip_output: When run live, this cell's output should match the behavior of the GIF below
    :offset: 1

I’ve tried to replicate this paradigm in our project, but it didn’t work. I get the error ERROR: Unknown directive type "notebook". So I guess this is a custom-made directive for sphinx, where does it come from? What role plays the second keyword “holoviews”?

The whole context of it is that we want to publish our notebooks on an HTML site. Nonetheless, our notebooks include DynamicMaps, so that we would desire to use the :skip_output: directive. The user would see a manually generated gif representing the DynamicMap, instead of a static image with a broken slider. Inspired by: Live Data — HoloViews v1.14.9

Moreover, the use of the notebook directive results in a very clean and modularized structure.

Many thanks in advance!

2

The notebook directive comes from the nbsite project. nbsite is maintained by the HoloViz group and is in practice dedicated to build the HoloViz websites, it’s probably not used by anyone outside of us, and we certainly don’t recommend using it! Yet it’s there so there’s nothing that prevents you from using it or from copying what you need and reuse that in your project. In an ideal world we would rely on some other package, that probably didn’t exist at the time nbsite was created. We’re not yet there though, either due to a simple lack of time or to missing functionality.

Instead of using nbsite you should have a look at myst-nb or nbsphinx, and there’s maybe more of them.

As for skipping the output, one simple way is to append ; to the end of your code cell (e.g. plot;), this is the standard way to suppress a code cell output in a notebook.

1 Like