Doc: Add instructions on how to run the SageMath jupyter kernel in a system jupyter notebook or jupyterlab

[mkoeppe]

For 9.4, we hope to automate it in #30306; but for Sage 9.3, perhaps we can at least explain to the user what needs to be done.

Further escalation in #30313: Doc: Add instructions how to run a remote SageMath jupyter kernel

CC: @nbruin @slel @jcamp0x2a @dimpase @paulmasson @embray

Component: documentation

Author: Matthias Koeppe

Branch/Commit: 726a0f9

Reviewer: François Bissey

Issue created by migration from https://trac.sagemath.org/ticket/30476

[mkoeppe]

Dependencies: #30246

[EmmanuelCharpentier]

comment:3

Works for me under Linux (locally) :

• $SAGE_ROOT/sage is symlinked to /usr/local/bin, which is in my default PATH.
• FWIW, the "small scripts" (Maxima, GAP, Pari) also live there.
• Some Jupyter kernels (gap and pari) are installed via Sage's pip.
• $SAGE_LOCAL/share/jupyter/kernels/sagemath/ has been symlinked (by root) to the system's Jupyter kernel directory (ditto for gap and pari).

ISTR that, on another machine, I managed to install Sage's kernel via

sudo jupyter kernelspec install [path to the Sage kernel directory]

But I can't check that ATM.

Notes:

• I wasn't able to get Singular's jupyter kernel to work (neither in Sages's jupyter nor the systemwide jupyter)..
• This also works with jupyterlab
• A valuable addition would be Maxima's jupyter kernel ; unfortunately, it does not (currently) works with an ECL-based Maxima...

HTH,

[malb]

comment:4

For me

jupyter kernelspec install --user $SAGE_ROOT/local/share/jupyter/kernels/sagemath

seems to work well https://martinralbrecht.wordpress.com/2020/08/23/conda-jupyter-and-emacs/

> jupyter console --kernel=sagemath
Jupyter console 5.2.0

┌────────────────────────────────────────────────────────────────────┐
│ SageMath version 9.1, Release Date: 2020-05-20                     │
│ Using Python 3.7.3. Type "help()" for help.                        │
└────────────────────────────────────────────────────────────────────┘


In [1]: singular("1")
Out[1]: 1

[mkoeppe]

comment:5

Thanks to both of you.

If you have chance, could you check / comment whether the following work in this configuration:

• interacts (most recently, Add optional packages jupyterlab, jupyterlab_widgets to support interacts in JupyterLab #30246 added support for them in JupyterLab)
• 3D graphics with threejs (in particular with online=False) or jsmol in the notebook / JupyterLab
• mathjax in the notebook / JupyterLab

[EmmanuelCharpentier]

comment:7

Replying to @mkoeppe:

[ Snip... ]

• mathjax in the notebook / JupyterLab

What do you mean ? The "standard" use of mathjax in Makdown cells ? That works as smoothly in the systemwide Jupyter as in Sage's Jupyter.

Or do you mean interpolation in a text cell of a Sage-generated value ?

[mkoeppe]

comment:8

Replying to @EmmanuelCharpentier:

Replying to @mkoeppe:

[ Snip... ]

• mathjax in the notebook / JupyterLab

What do you mean ? The "standard" use of mathjax in Makdown cells ? That works as smoothly in the systemwide Jupyter as in Sage's Jupyter.

Or do you mean interpolation in a text cell of a Sage-generated value ?

Great question, I am not actually sure. But src/sage/repl/ipython_kernel/install.py (use_local_mathjax) installs a copy of mathjax in Sage's jupyter - and the jupyter kernelspec install command does not copy that over to the system jupyter if I'm not mistaken.

[mkoeppe]

comment:9

Replying to @malb:

jupyter kernelspec install --user $SAGE_ROOT/local/share/jupyter/kernels/sagemath

seems to work well

This seems currently broken: #30903 (Fix broken symlink to documentation in the Sage jupyter kernelspec)

[mkoeppe]

Changed dependencies from #30246 to #30903

[mkoeppe]

comment:11

Replying to @EmmanuelCharpentier:

• A valuable addition would be Maxima's jupyter kernel ; unfortunately, it does not (currently) works with an ECL-based Maxima...

Is this already discussed somewhere?

[EmmanuelCharpentier]

comment:12

Replying to @mkoeppe:

Replying to @EmmanuelCharpentier:

• A valuable addition would be Maxima's jupyter kernel ; unfortunately, it does not (currently) works with an ECL-based Maxima...

Is this already discussed somewhere?

In the Maxima Jupyter kernel Githib page, IIRC. Don't have any more precise reference ATM...

[EmmanuelCharpentier]

comment:13

Replying to @mkoeppe:

Thanks to both of you.

If you have chance, could you check / comment whether the following work in this configuration:

• interacts (most recently, Add optional packages jupyterlab, jupyterlab_widgets to support interacts in JupyterLab #30246 added support for them in JupyterLab)
• 3D graphics with threejs (in particular with online=False) or jsmol in the notebook / JupyterLab
• mathjax in the notebook / JupyterLab

In the Jupyter notebook, updating a worksheet created in Sage's notebook :

• Mathjax in markdown cells : OK
• Interacts : the graph is diplayed with the interact's default value, the slider is not displayed (I get a 404 in the console where I launched !Jupyter)
• 3D plot with default viewer : works (threjs)
• 3D plot with lmol : blank space (and a 404 in the console)
• 3D plot with jsmol : warning, and plot displayed with threejs.

I uploaded the sheet and a capture of console output/error (Essai interact.tar.gz).

[mkoeppe]

comment:14

Attachment: Essai interact.tar.gz

Thanks very much!

Could you repeat the 3D plotting experiment with online=False, for example using sphere(online=False)?

[EmmanuelCharpentier]

comment:15

Replying to @mkoeppe:

Thanks very much!

Could you repeat the 3D plotting experiment with online=False, for example using sphere(online=False)?

Works.

[EmmanuelCharpentier]

comment:16

Do you have an idea about how to add Sage-specific Jupyter extensions (Sage's interacts, jmol) to the systemwide notebook ? If possible, as root (in order to be usable by all users) ?

[mkoeppe]

comment:17

Replying to @EmmanuelCharpentier:

Replying to @mkoeppe:

Could you repeat the 3D plotting experiment with online=False, for example using sphere(online=False)?

Works.

With all 3 options, or only threejs?

[mkoeppe]

comment:18

Replying to @EmmanuelCharpentier:

Do you have an idea about how to add Sage-specific Jupyter extensions (Sage's interacts, jmol) to the systemwide notebook ? If possible, as root (in order to be usable by all users) ?

For the Sage interacts, one needs the pip-installable package widgetsnbextension.
It would be best to recommend to users to install it as a system package (see https://repology.org/projects/?search=widgetsnbextension); if not available, it can be installed by pip.

[mkoeppe]

comment:19

Let's add system package information for widgetsnbextension on this ticket.
(#30124 is a more ambitious ticket in the same direction.)

[mkoeppe]

Branch: u/mkoeppe/doc__add_instructions_on_how_to_run_the_sagemath_jupyter_kernel_in_a_system_jupyter_notebook_or_jupyterlab

[EmmanuelCharpentier]

comment:21

Replying to @mkoeppe:

Replying to @EmmanuelCharpentier:

Replying to @mkoeppe:

Could you repeat the 3D plotting experiment with online=False, for example using sphere(online=False)?

Works.

With all 3 options, or only threejs?

• default ==> threejs
• jmol ==> blank space
• jsmol ==> warning + threejs

---

New commits:

438bc88

build/pkgs/widgetsnbextension/distros: New

[EmmanuelCharpentier]

Commit: 438bc88

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

e4fe231

build/pkgs/widgetsnbextension/distros: Add more

[sagetrac-git]

Changed commit from 438bc88 to e4fe231

[mkoeppe]

comment:23

(The information for conda is added in #28745.)

[mkoeppe]

comment:24

Replying to @mkoeppe:

Replying to @EmmanuelCharpentier:

Do you have an idea about how to add Sage-specific Jupyter extensions (Sage's interacts, jmol) to the systemwide notebook ? If possible, as root (in order to be usable by all users) ?

For the Sage interacts, one needs the pip-installable package widgetsnbextension.
It would be best to recommend to users to install it as a system package (see https://repology.org/projects/?search=widgetsnbextension); if not available, it can be installed by pip.

I have added the system package information. Could you check whether installing the system package on your system gets the interacts to work?

[mkoeppe]

Changed dependencies from #30903, #30972, #30315 to none

[mkoeppe]

Author: Matthias Koeppe

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

d064f45	build/pkgs/widgetsnbextension/distros: New
7023a4a	build/pkgs/widgetsnbextension/distros: Add more
6072c20	src/doc/en/installation/launching.rst: Add section 'Setting up [SageMath](../wiki/SageMath) as a Jupyter kernel in an existing Jupyter notebook or JupyterLab installation'
5d8a300	src/doc/en/installation/launching.rst: Installation of jupyter-jsmol
9010d38	Expand documentation

[sagetrac-git]

Changed commit from aab83ee to 9010d38

[sagetrac-git]

Changed commit from 9010d38 to 3ff959c

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

3ff959c

src/doc/en/installation/launching.rst: Add code examples provided by charpent

[kiwifb]

comment:46

I am finding that wording a bit convoluted - and not a usual English formulation (yes I know that criticism comes from a French person)

For the full functionality of the SageMath kernel in your global
Jupyter installation, additionally some Notebook Extension packages
need to be installed (or linked) into the environment from which the
Jupyter installation runs.

I would suggest to replace it by something along the lines of

To get the full functionality of the SageMath kernel in your global 
Jupyter installation, the following Notebook Extension packages also 
need to be installed (or linked) in the environment from which the
Jupyter installation runs.

A native English speaker may want to polish it a bit.

It is otherwise quite good and would give it a positive review.

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

dec079e

Rewording as suggested

[sagetrac-git]

Changed commit from 3ff959c to dec079e

[slel]

comment:48

Would this work only on Linux and macOS?

Someone requested similar instructions for Windows at

• Ask sage question 54022: Install SageMath into Jupyter in Windows 10 rather than the reverse

[mkoeppe]

comment:49

For a simpler version of this I have opened #31156.

[mkoeppe]

comment:50

Replying to @slel:

Someone requested similar instructions for Windows at

• Ask sage question 54022: Install SageMath into Jupyter in Windows 10 rather than the reverse

For this I have opened #31157.

[mkoeppe]

comment:51

The present ticket still needs review!

[kiwifb]

comment:52

There. 44 emails to go (down from 378) after being without any internet since Wednesday.

[kiwifb]

Reviewer: François Bissey

[mkoeppe]

comment:53

Thanks!

[vbraun]

comment:54

[dochtml] [installat] The HTML pages are in local/share/doc/sage/html/en/installation.
[dochtml] Error building the documentation.
[dochtml] Traceback (most recent call last):
[dochtml]   File "/usr/lib64/python3.9/runpy.py", line 197, in _run_module_as_main
[dochtml]     return _run_code(code, main_globals, None,
[dochtml]   File "/usr/lib64/python3.9/runpy.py", line 87, in _run_code
[dochtml]     exec(code, run_globals)
[dochtml]   File "/home/release/Sage/local/lib64/python3.9/site-packages/sage_setup/docbuild/__main__.py", line 2, in <module>
[dochtml]     main()
[dochtml]   File "/home/release/Sage/local/lib64/python3.9/site-packages/sage_setup/docbuild/__init__.py", line 1730, in main
[dochtml]     builder()
[dochtml]   File "/home/release/Sage/local/lib64/python3.9/site-packages/sage_setup/docbuild/__init__.py", line 352, in _wrapper
[dochtml]     build_many(build_other_doc, L)
[dochtml]   File "/home/release/Sage/local/lib64/python3.9/site-packages/sage_setup/docbuild/__init__.py", line 295, in build_many
[dochtml]     _build_many(target, args, processes=NUM_THREADS)
[dochtml]   File "/home/release/Sage/local/lib64/python3.9/site-packages/sage_setup/docbuild/utils.py", line 289, in build_many
[dochtml]     raise worker_exc.original_exception
[dochtml] OSError: /home/release/Sage/src/doc/en/installation/launching.rst:90: WARNING: Could not lex literal_block as "bash". Highlighting skipped.
[dochtml] 
[dochtml]     Note: incremental documentation builds sometimes cause spurious
[dochtml]     error messages. To be certain that these are real errors, run
[dochtml]     "make doc-clean" first and try again.
make[3]: *** [Makefile:1877: doc-html] Error 1

[sagetrac-git]

Changed commit from dec079e to 726a0f9

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

726a0f9

src/doc/en/installation/launching.rst: Fix markup

[vbraun]

Changed branch from u/mkoeppe/doc__add_instructions_on_how_to_run_the_sagemath_jupyter_kernel_in_a_system_jupyter_notebook_or_jupyterlab to 726a0f9