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

[charpent]

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]

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]

Thanks to both of you.

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

• interacts (most recently, #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

[charpent]

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]

Replying to charpent:

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]

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]

Replying to charpent:

• 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?

[charpent]

Replying to mkoeppe:

Replying to charpent:

• 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...

[charpent]

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, #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]

Thanks very much!

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

[charpent]

Replying to mkoeppe:

Thanks very much!

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

Works.

[charpent]

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]

Replying to charpent:

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]

Replying to charpent:

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]

Let's add system package information for widgetsnbextension on this ticket.

[charpent]

Replying to mkoeppe:

Replying to charpent:

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

[git]

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

​e4fe231

build/pkgs/widgetsnbextension/distros: Add more

[mkoeppe]

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

[mkoeppe]

Replying to mkoeppe:

Replying to charpent:

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?

[charpent]

Replying to mkoeppe:

Replying to mkoeppe:

Replying to charpent:

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?

It doesn't : both jupyter-nbextension-jupyter-js-widgets and python3-widgetsnbextension were already installed :

charpent@zen-book-flip:~$ dpkg -l "*jupyter*widgets*" | cat
Souhait=inconnU/Installé/suppRimé/Purgé/H=à garder
| État=Non/Installé/fichier-Config/dépaqUeté/échec-conFig/H=semi-installé/W=attend-traitement-déclenchements
|/ Err?=(aucune)/besoin Réinstallation (État,Err: majuscule=mauvais)
||/ Nom                                    Version      Architecture Description
+++-======================================-============-============-================================================
ii  jupyter-nbextension-jupyter-js-widgets 6.0.0-6      all          Interactive widgets - Jupyter notebook extension
charpent@zen-book-flip:~$ dpkg -l "*widgets*extension*" | cat
Souhait=inconnU/Installé/suppRimé/Purgé/H=à garder
| État=Non/Installé/fichier-Config/dépaqUeté/échec-conFig/H=semi-installé/W=attend-traitement-déclenchements
|/ Err?=(aucune)/besoin Réinstallation (État,Err: majuscule=mauvais)
||/ Nom                        Version      Architecture Description
+++-==========================-============-============-===========================================================
ii  python3-widgetsnbextension 6.0.0-6      all          Interactive widgets - Jupyter notebook extension (Python 3)

From apt-cache show python3-widgetsnbextension :

This package should *not be necessary* for Debian software to use; instead you should directly use the jupyter-nbextension-jupyter-js-widgets package. It is provided only for compatibility with non-Debian software.

HTH,

[charpent]

IMPORTANT : when I replied, I didn't see the new commits. So this answer is invalid.

I'll switch to this new branch and retry.

Sorry for the noise...

[ Snip... ]

[mkoeppe]

Not at all - the commits don't do anything - at the moment these are just information files that will influence the system package messages at the end of "configure"

[mkoeppe]

On your system, how do you start the system Jupyter notebook? With the same Jupyter installation, could you run jupyter nbextension list?

[charpent]

Console putpur attempting an interact with #30476 up to commit e4fe231f7260c51f51d8079d92b3ad68b2111098

[charpent]

Replying to charpent:

IMPORTANT : when I replied, I didn't see the new commits. So this answer is invalid.

I'll switch to this new branch and retry.

Sorry for the noise...

No joy. Still no slider... See console output/error in the uploaded Essai interact-2.log.

[charpent]

Replying to mkoeppe:

On your system, how do you start the system Jupyter notebook?

Command line : jupyter notebook or jupyter notebook --browser=google-chrome according to what I have in my default) chromium.

With the same Jupyter installation, could you run jupyter nbextension list?

charpent@zen-book-flip:~$ jupyter nbextension list
Known nbextensions:
  config dir: /home/charpent/.jupyter/nbconfig
    notebook section
      nbextensions_configurator/config_menu/main  enabled 
      - Validating: problems found:
        - require?  X nbextensions_configurator/config_menu/main
      python-markdown/main  enabled 
      - Validating: OK
    tree section
      nbextensions_configurator/tree_tab/main  enabled 
      - Validating: problems found:
        - require?  X nbextensions_configurator/tree_tab/main
  config dir: /usr/local/etc/jupyter/nbconfig
    notebook section
      nbextensions_configurator/config_menu/main  enabled 
      - Validating: problems found:
        - require?  X nbextensions_configurator/config_menu/main
      contrib_nbextensions_help_item/main  enabled 
      - Validating: OK
    tree section
      nbextensions_configurator/tree_tab/main  enabled 
      - Validating: problems found:
        - require?  X nbextensions_configurator/tree_tab/main
  config dir: /etc/jupyter/nbconfig
    notebook section
      jupyter-js-widgets/extension  enabled 
      - Validating: OK

Ooops..

[charpent]

In the Nbextensions tab, the following are enabled :

• jupyter-js-widgets/nbextension
• Nbextension edit menu item
• Python Markdown
• contrib_nbextensions_help_item
• Nbextensions dashboard tab

HTH,

Replying to charpent:

Replying to mkoeppe:

On your system, how do you start the system Jupyter notebook?

Command line : jupyter notebook or jupyter notebook --browser=google-chrome according to what I have in my default) chromium.

With the same Jupyter installation, could you run jupyter nbextension list?

charpent@zen-book-flip:~$ jupyter nbextension list
Known nbextensions:
  config dir: /home/charpent/.jupyter/nbconfig
    notebook section
      nbextensions_configurator/config_menu/main  enabled 
      - Validating: problems found:
        - require?  X nbextensions_configurator/config_menu/main
      python-markdown/main  enabled 
      - Validating: OK
    tree section
      nbextensions_configurator/tree_tab/main  enabled 
      - Validating: problems found:
        - require?  X nbextensions_configurator/tree_tab/main
  config dir: /usr/local/etc/jupyter/nbconfig
    notebook section
      nbextensions_configurator/config_menu/main  enabled 
      - Validating: problems found:
        - require?  X nbextensions_configurator/config_menu/main
      contrib_nbextensions_help_item/main  enabled 
      - Validating: OK
    tree section
      nbextensions_configurator/tree_tab/main  enabled 
      - Validating: problems found:
        - require?  X nbextensions_configurator/tree_tab/main
  config dir: /etc/jupyter/nbconfig
    notebook section
      jupyter-js-widgets/extension  enabled 
      - Validating: OK

Ooops..

[enriqueartal]

I have two installations. In my laptop, I installed notebook jupyter via pip as root and also jupyterlab (right now 3.0.0rc10). I linked the jupyter kernel folder of my sage installation in .local/share/jupyter/kernels/sagemath and I launch it with jupyter lab in the command line or via a desktop file. I linked also the nbextensions mathjax, threejs and jsmol of the sage installation in the jupyter folder. It works, including threejs with online=False.

I also have a similar installation in the desktop computer of my office, using also jupyterhub (standard configuration, I may share my conf file), with basically the same installation, with some exceptions. I use the stable version of jupyterlab. I cannot use jmol as viewer, but otherwise everything works.

[enriqueartal]

One more comment for jupyterhub. If the user has not set the variable SAGE_ROOT, then the kernel.json file must include the variable "env" with the value { "SAGE_ROOT": "place_where_Sage_is_installed" }, see ​https://benjamin-hackl.at/blog/2016/03/jupyterhub-sagemath.html.

[git]

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

​64dad42	build/pkgs/widgetsnbextension/distros: New
​36c1ab6	build/pkgs/widgetsnbextension/distros: Add more
​edabc97	src/doc/en/installation/launching.rst: Add section 'Setting up SageMath as a Jupyter kernel in an existing Jupyter notebook or JupyterLab installation'

[mkoeppe]

I've started a new section in the documentation.

Could someone in the know please add instructions on how to verify that all the features are working?

[git]

Branch pushed to git repo; I updated commit sha1. Last 10 new commits:

​db1b38c	build/pkgs/jmol/spkg-install.in: No longer install jsmol
​95a7131	sage.repl.display.jsmol_iframe: Adjust path to jsmol
​98b83f5	sage.repl.ipython_kernel.install: No longer symlink jsmol
​40a8823	build/pkgs/jupyter_jsmol: Add dependencies, install-requires.txt
​bf3c1dc	build/pkgs/jupyter_jsmol/spkg-install.in: Do not rebuild the javascript file
​f2a02d9	Get rid of JSMOL_DIR
​7732e2e	build/pkgs/jmol/SPKG.rst: Update
​80a3db1	build/pkgs/jupyter_jsmol/spkg-install.in: Use sdh_setup_bdist_wheel
​58c1873	Merge branch 't/30315/switch_jsmol_to_jupyter_jsmol__make_jmol_optional' into t/30476/doc__add_instructions_on_how_to_run_the_sagemath_jupyter_kernel_in_a_system_jupyter_notebook_or_jupyterlab
​aab83ee	src/doc/en/installation/launching.rst: Installation of jupyter-jsmol

[fbissey]

#30972 doesn't seem technically needed for this to work. I guess it is a nice to have but not a show stopper. Also, the author field should be filled. I will give it a second more attentive reading once it is done.

[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 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

[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

[fbissey]

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.

[git]

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

​dec079e

Rewording as suggested

[slelievre]

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]

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

[mkoeppe]

Replying to slelievre:

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]

The present ticket still needs review!

[fbissey]

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

[mkoeppe]

Thanks!

[vbraun]

[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

[git]

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

​726a0f9

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