Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a topic on jupyter-lmod in documentation #640

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
50 changes: 50 additions & 0 deletions docs/source/370_jupyter_lmod.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
Jupyter and Lmod
================

It is possible to use Lmod inside of Jupyter with the terminal or jupyter-lmod.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe add a link to your repo from the start 🙂

Suggested change
It is possible to use Lmod inside of Jupyter with the terminal or jupyter-lmod.
It is possible to use Lmod inside of Jupyter with its terminal or the Jupyter extension `jupyter-lmod <https://github.com/cmd-ntrf/jupyter-lmod>`_.


jupyter-lmod is a frontend and server extension for Jupyter (notebook and jupyterlab).
The extension provides most of Lmod functionalities graphically:
- Browser and filter available modules
- Load and unload modules
- Display a module content
- Create and load collections

Installation
~~~~~~~~~~~~

To install jupyter-lmod extension: ::

pip install jupyterlmod
cmd-ntrf marked this conversation as resolved.
Show resolved Hide resolved

This enables the extension for both Jupyter Notebook and JupyterLab.

How does it work?
~~~~~~~~~~~~~~~~~

jupyter-lmod uses lmod python interface to generate Python code
that modifies the environment variables of the Python process running Jupyter. All child
processes of Jupyter (including kernels) created after Lmod calls inherit
the environment variables as defined by the set of loaded modules.
cmd-ntrf marked this conversation as resolved.
Show resolved Hide resolved
Comment on lines +29 to +32
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence is a bit confusing, I suggest to simplify it:

Suggested change
jupyter-lmod uses lmod python interface to generate Python code
that modifies the environment variables of the Python process running Jupyter. All child
processes of Jupyter (including kernels) created after Lmod calls inherit
the environment variables as defined by the set of loaded modules.
jupyter-lmod uses lmod python interface to generate Python code
that modifies the environment variables of the Python process running Jupyter. All child
processes of Jupyter (*e.g.* newly spawned kernels) will inherit the environment
as currently defined by the set of loaded modules.


Lmod environment variable configuration for jupyter-lmod
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The plugin requires the environment variable **$LMOD_CMD** to be defined when Jupyter starts,
plus all environment variables required by Lmod to work properly (i.e.: **$MODULEPATH**).

Some JupyterHub spawners do not setup the complete user's environment, leaving **$LMOD_CMD**
and **$MODULEPATH** undefined. To address this issue, the environment variables have to be
defined in **jupyterhub_config.py** using
`c.Spawner.environment <https://jupyterhub.readthedocs.io/en/stable/api/spawner.html#jupyterhub.spawner.Spawner.environment>`_.

If the environment variables are defined before JupyterHub launch, you can add their
name only to `c.Spawner.env_keep <https://jupyterhub.readthedocs.io/en/stable/api/spawner.html#jupyterhub.spawner.Spawner.env_keep>`_
instead.

References
~~~~~~~~~~

For more information, refer to jupyter-lmod github repo:
https://www.github.com/cmd-ntrf/jupyter-lmod

1 change: 1 addition & 0 deletions docs/source/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,7 @@ Advanced Topics
340_inherit
350_community
360_check_syntax
370_jupyter_lmod

Internal Structure of Lmod
^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand Down