embed rendered notebooks in ordinary .rst

[mgasner]

Probably a dupe of #181, but it would be really great to be able to embed a rendered notebook into an ordinary .rst file. This is for the case where you aren't using notebooks to generate your docs, but rather documenting a system that is meant to be used in notebooks.

[mgasner]

(This is like an extended, fancier version of what you can currently do with the undocumented .. nbinput:: and .. nboutput:: directives).

[mgeier]

Yes #181 discusses including one or more notebooks within RST files, and it mentions the un-merged PR #33, which suggested a possible implementation. I mentioned my concerns there.

A slightly different approach has been taken by https://github.com/vidartf/nbsphinx-link, you should try if that is appropriate for your use case!

You should not use the nbinput and nboutput directives, because I consider them implementation details and they may even be removed in a future version.

But I've recently read about yet another approach: https://blog.jupyter.org/integrating-output-in-documentation-with-jupyter-sphinx-ecf569ddab85 https://jupyter-sphinx.readthedocs.io/en/latest/ https://github.com/jupyter-widgets/jupyter-sphinx

Probably that's what you need?

[mgasner]

Thanks very much. The jupyter-sphinx system looks great if what you are interested in doing is generating embedded plots, etc., from code that runs on a jupyter kernel, but where you aren't concerned about notebook formatting details.

In my case, I'm trying to document a system that is meant to be invoked interactively by users of jupyter notebooks -- so what I really want to do is render individual notebook cells (and perhaps their output) in sphinx docs as they would appear in jupyter itself. Your internal directives are the closest thing I've found that match this case.