Replace mentions of `jupyter` image with `python:v2`

[StevenMaude]

Related to #1568: we have some mentions of opensafely jupyter in the documentation still.

The OpenSAFELY jupyter-docker image repository was archived in January 2024, so we should update the documentation and instead suggest using the python:v2 image.

Edit: see below. We do have a run: jupyter that should be fixed up though.

[bloodearnest]

Some context. There are two things named jupyter.

1. We publish the python:v1 image as jupyter, so that ancient run: jupyter ... commands still work in project.yaml: https://github.com/opensafely-core/python-docker/blob/main/scripts/publish.sh#L30
   This is b/w compat thing, from when we used to have a separate jupyter image. I am not sure can change this without doing the work to deprecate/migrate away from using :latest tags, as discussed here: https://docs.google.com/document/d/1TTK6ljOUaERAMX8pKi2bYMWqlSghaxRrj2ajw4FxufM/edit#heading=h.rzq3ae47vb6t

2. opensafely jupyter is a completely different beast. It uses the python:v1 image to spin up a local jupyterlab environment for developing notebooks interactively locally. It does not depend on, and is not related to, the jupyter docker image. Such notebooks can be run in project.yaml with python:v1 nbconvert. The name jupyter is just the local command.
   https://github.com/opensafely-core/opensafely-cli/blob/main/opensafely/jupyter.py#L178

I've spotted a bug there, which is related to this issue: opensafely jupyter should explicitly use python:v1 (currently uses python:latest), and allow you so specify python:v2 (there was an idea that we would add support for R notebooks to opensafely jupyter if the need arose).

I don't know current plans or decisions (are we removing support for notebooks?) but I would suggest:

• we switch to using explicit python:v1 in the opensafely jupyter command, and add a way to specify v2. I think we could switch to v2 by default if we want (good time to switch a default atm!)
• we should remove any references to run: jupyter in the docs if there are any (a quick search couldn't find any).
• we update the docs section on running notebooks to clarify that:
  • running a notebook in project.yaml should be run: python:v2 nbconvert notebook.ipynb
  • opensafely jupyter is helpful way to get a normal jupyter development environment locally, to develop said notebook.

Possibly that is a different ticket?

[StevenMaude]

@bloodearnest: Thanks for the clarification; that's really helpful, having not really used this feature before.

(are we removing support for notebooks?)

No.¹

So really, this issue should be about:

• we should remove any references to run: jupyter in the docs if there are any (a quick search couldn't find any).

• we update the docs section on running notebooks to clarify that:

  • running a notebook in project.yaml should be run: python:v2 nbconvert notebook.ipynb
  • opensafely jupyter is helpful way to get a normal jupyter development environment locally, to develop said notebook.

I'll open an OpenSAFELY CLI issue for:

• we switch to using explicit python:v1 in the opensafely jupyter command, and add a way to specify v2. I think we could switch to v2 by default if we want (good time to switch a default atm!)

Footnotes

1. The surrounding context is: can we encourage users in Codespaces to use the Docker images corresponding to the non-Docker environment that they can also work in (currently the installed packages are based on r:latest and python:v2)? ↩