Enable Jupyter Sphinx Extension in docs?

While writing documentation, I noticed the extended use of the IPython Sphinx Directive.

I bet most pvlib users like to play with pvlib in interactive environments. However, I think Jupyter Notebooks are getting more common/widespread when compared to IPython consoles. I wondered if it would be acceptable to allow code in the documentation to look more like notebooks instead of consoles.

There is this extension called Jupyter Sphinx, under the umbrella of the Jupyter organization.

I think it could have a couple of advantages:

• Simpler code (i.e.: no need to @savefig)
• Removal of In [xx]:, which makes it harder to read, copy and paste
• Easier to read, since blank lines are honored in the code
• More similarities to a Jupyter notebook (so maybe more user-friendly for readers)
• Allows to hide input/output
• Allows to download as a Notebook or Python script
• Allows to emphasize lines in a cell (very useful when wanting to highlight something in the documentation)
• The style can be tweaked to, for example, remove the box shadows (to avoid changing too much the current looks of the docs)
• Allows for interactive plots with Plotly, and Pandas has a Plotly backend, so it would be very easy to have interactive plots in the documentation without adding clutter nor assuming readers need to know about Plotly/Matplotlib

A couple of (maybe) disadvantages:

• Not sure PDF (i.e.: LaTeX) export would work when using interactive plots
• ipywidgets would definitely be not rendered in PDF (https://github.com/jupyter/jupyter-sphinx/issues/61)
• ?? does not work (only used in modelchain.rst); see https://github.com/jupyter/nbclient/issues/196 (maybe replaceable by sphinx-code-include)
• Add more development dependencies (if both IPython and Jupyter were to be allowed)
• Required migration (if Jupyter was to replace IPython completely)
• Performance may be slower?

[Peque]

@wholmgren It’s true that the directive had 3 commits in the last 2 years, and the documentation still states:

The IPython Sphinx Directive is in ‘beta’ and currently under active development. Improvements to the code or documentation are welcome!

jupyter-sphinx seems to be a bit more active and there does not seem to be a “beta” statement in the docs.

PS: Cross-referencing https://github.com/jupyter/jupyter-sphinx/issues/36.

[kanderso-nrel]

Thanks for the thorough summary @Peque! Just to have something to look at, here’s the result of naively replacing ipython w/ jupyter-execute:

• jupyter-execute: https://pvlib-python--1380.org.readthedocs.build/en/1380/user_guide/modelchain.html
• ipython: https://pvlib-python.readthedocs.io/en/latest/user_guide/modelchain.html

Of course blocks of code with multiple outputs only show the last output now, so a little restructuring would be needed. Also, it seems like ?? doesn’t work?