Explainers, Pedagogy, and Notebooks

[bnord]

(Astro)physicists are accustomed to having notebooks that can be run right out of the gate when they pick up a new project or code base. Also, the short time frames of internships and other activities make it important that users can figure out how to use code quickly; often, having a jupyter notebook that runs without issues can serve these purposes.

However, it appears that jupyter is a heavyweight dependency.

is there a way to allow for this dependency (in our fastsim repo's, for example) despite its heaviness?

is there another we can use that will allow people to run something immediately and get the visualizations?

I think the HTML versions of the notebooks may not suffice.

[voetberg]

Notebooks can be included without using jupyter as a dependency. If someone is installing a package, they still need to run a kernel to start a notebook, and if notebooks are as universal as you describe, I think it's a reasonable expectation that they know how to start a kernel without it being installed automatically.

An alternate is to include a link to a colab notebook, or instructions to open the code in colab.

[voetberg]

I do want to hear your justification why showing examples is insufficient. Is there a wider expectation that people won't know how to start up code on their own? Or is the standard for people to always install from source and do their work within the source package instead of adding to a larger package?

[bnord]

Or maybe if there were a way for people to load the HTML into google colab and run it, perhaps that would suffice.

[voetberg]

In that case, including a notebook (but not having jupyter as an install dependency), is totally doable. Instructions to copy to colab works (just direct people to this link), or simply stating "To open our example notebooks, run pip install jupyter; jupyter-notebook ./notebooks" also work

[voetberg]

I suppose the main reason I push back on saying "Just give people an example with a jupyter notebook" is two fold; 1. It is a crutch people can rely on instead of writing good documentation. It limits what people can learn to do with your code down the road, 2. You can't properly develop in jupyter notebooks. If we want to install good practices, in both our group and the community as a whole, we should try to encourage people to write code that is designed to be used by other people, outside the narrow scope of their own projects.

[bnord]

I agree with you on both your points. I'm trying to either a) split the difference or b) have it both ways -- I'm not sure which, though, lol.

I'm leaning into to making something as easy as possible for people to adopt AND saying that it's up to the user to use it properly.

[voetberg]

I think directing people to colab is probably the closest to split the difference we can then. Perhaps there should be a policy of linking to documentation when talking about more advanced behavior, and keeping the notebook for exclusively simple solutions (e.g. Import the package, execute the simplest version of the code).

[voetberg]

I think I have a solution to this, after having to work a little in colab for running tutorials.

When making a documentation page, it is simple enough to add a 'open in colab' button at the top of an embedded HTML page.

This would look having a documentation rst page that looks like:

Example
---------

.. image:: https://colab.research.google.com/assets/colab-badge.svg 
   :target: https://colab.research.google.com/github/{path to the example notebook}

.. raw:: html
   :file: examples/{example notebook exported}.html

Which produces a page that looks like this: