Repository navigation
docs: Generate notebook outputs for web display #268
Description
Currently, we do not show notebook outputs. It would be helpful to do so. However, we do not want to store the outputs in Git because they pollute diffs.
We should investigate the solution used by Scikit-learn:
- No output in Git:
https://github.com/scikit-learn/scikit-learn/blob/master/examples/datasets/plot_digits_last_image.py
https://github.com/scikit-learn/scikit-learn.github.io/blob/master/dev/_downloads/plot_digits_last_image.ipynb - Output on the web:
http://scikit-learn.org/stable/auto_examples/datasets/plot_digits_last_image.html
Activity
docs: Use sphinx-gallery
docs: Use sphinx-gallery
docs: Use sphinx-gallery
bug fix on printing exception traceback (#268)
mihaic commentedon Feb 27, 2018
I think Sphinx-gallery, the solution used by Scikit-learn is not ideal, as discussed in PR #270, where I was trying to use it.
Instead, I think we should use a solution that works directly with Jupyter notebooks, without converters, potentially Nbsphinx:
https://github.com/spatialaudio/nbsphinx
mshvartsman commentedon Apr 23, 2018
I did some poking at this, but it is (unfortunately) not trivial. WIP in https://github.com/mshvartsman/brainiak/tree/nbsphinx. There's a few issues keeping this from working:
nbsphinx seems to want notebooks in
toctreedirectives rather than..includedirectives in the rst files. Using relative paths in..includeworks fine to find notebooks underexamplesbut sphinx tries to process them as rst files. Using relative paths undertoctreeseems to not find anything abovedocs. As per http://www.sphinx-doc.org/en/1.5.1/markup/toctree.html,Relative document names (not beginning with a slash) are relative to the document the directive occurs in, absolute names are relative to the source directory.This sounds like relative paths with..should work but sensible things like../examples/testor/examples/testorexamples/testdon't seem to work. An easy but hacky workaround is symlinking examples inside docs during the build process (something we can do in the makefile). I'm open to better options here.With
examplessymlinked underdocs, we run into another issue, which is that notebook rendering doesn't seem to respect environments. We need to figure out a way to tell nbsphinx whichnbconvertto use (which should be the one that is in the env that the builder itself created).mihaic commentedon Apr 15, 2021
I found a plugin that allows nbsphinx to use notebooks outside
docs:https://github.com/vidartf/nbsphinx-link
I tested it and it works fine. Before submitting a PR, I need to figure out how to separate documentation building from unit testing, because it will not be feasible to run them together anymore.
mihaic commentedon Apr 15, 2021
MyST-NB is a recent project for executing notebooks in Sphinx. It also works in my simple testing. One advantage over nbsphinx is that it does not depend on Pandoc (which is large and not on PyPI). However, it does not appear to support notebooks outside the Sphinx root:
executablebooks/MyST-NB#297
mihaic commentedon May 28, 2021
We ended up going with MyST-NB and it seems to be going well:
https://github.com/brainiak/brainiak/runs/2689575413?check_suite_focus=true#step:6:938
I will leave this issue open until we integrate all the existing notebooks.