Documentation for pip install misleading

[knuesel]

Hi, the documentation for installing with pip says:

pip install RISE

Note: Before RISE 5.4.2, it was necessary to perform one more step to install the JS and CSS in the proper places with

jupyter-nbextension install rise --py --sys-prefix

This is not needed anymore because those resources are installed automatically by the setup.py when you pip install the package.

This is probably true under some conditions, but failed on Ubuntu 20.04. I'm not very familiar with the Python ecosystem but from what I understand:

1. By default, pip3 installs the package using the wheel archive, so setup.py will not be run.
2. Trying to fix it with the proposed command fails, because --sys-prefix outside a virtualenv/conda environment tries to install system-wide which is not permitted (unless running as root or with sudo) and is probably not what the user wants

[parmentelat]

The point here is, our doc is no place for describing all the options to
jupyter nbextensions so we need to pick one and only one variant so people get the gist of it and adapt to their needs (same goes for pip btw, although it’s probably better known)

it seemed to me that this variant was the one likely to be useful as-is to most people

If you’d like to reword the doc so that this is more explicit we’ll be happy to take a PR

Now the other thing that you mention about the extra installation step being mandatory on ubuntu is more of a concern to me; in principle a whole section that we are discussing right now could have gone away altogether in the near future, But that would be true only if things work as expected and so if it’s not the case we need to fix that

Can you please elaborate a little on how to reproduce the issue ?

Sent from my iPhone

On 17 May 2020, at 16:41, Jeremie Knuesel notifications@github.com wrote:

Hi, the documentation for installing with pip says:

pip install RISE Note: Before RISE 5.4.2, it was necessary to perform one more step to install the JS and CSS in the proper places with

jupyter-nbextension install rise --py --sys-prefix This is not needed anymore because those resources are installed automatically by the setup.py when you pip install the package.

This is probably true under some conditions, but failed on Ubuntu 20.04. I'm not very familiar with the Python ecosystem but from what I understand:

By default, pip3 installs the package using the wheel archive, so setup.py will not be run. Trying to fix it with the proposed command fails, because --sys-prefix outside a virtualenv/conda environment tries to install system-wide which is not permitted (unless running as root or with sudo) and is probably not what the user wants — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or unsubscribe.

[knuesel]

Here's a quick way to reproduce with Docker:

1. Run Docker image for latest Ubuntu version (also tested with Debian, same results):

   docker run -it --network=host ubuntu

2. In the Docker container, install pip:

   apt update && apt install python3-pip

3. Create a normal user

   adduser test

4. Use the test user to install RISE

   su test
   cd
   export PATH=$PATH:$HOME/.local/bin
   pip3 install rise

5. Start the notebook and observe that RISE is not enabled

   jupyter-notebook

The same problem occurs when installing Jupyter from the jupyter-notebook Ubuntu package rather than using pip (then installing RISE with pip).

In all cases it works after running jupyter nbextension enable rise --user --py.

I think the problem is that the wheel package installs the file ~/.local/etc/jupyter/nbconfig/notebook.d/rise.json which is not read by Jupyter. The jupyter nbextension enable command writes the configuration to ~/.jupyter/nbconfig/notebook.json, but it also works when placing the file rise.json in ~/.local/etc/jupyter/nbconfig/notebook.d.

[damianavila]

It is probably a PATH issue... from above, you are using PATH=$PATH:$HOME/.local/bin. I would bet that is locating the rise.json file in a place the Jupyter Notebook does not look for by default. We could probably add a note about this sort of case in the docs.

[knuesel]

@damianavila I set the PATH as a quick fix to write all commands in the same session. I'm pretty sure it's unrelated: $HOME/.local/bin is a standard directory for user binaries. It happens to be used by pip for executables, that's actually where pip installs the executable for Jupyter itself so that should make no issue.

Why I set the PATH manually: The default .profile file in Ubuntu will add $HOME/.local/bin to the PATH when the user logs in, if the directory exists. In the commands above, I used su test which doesn't make a real login, and anyway the directory doesn't exist (so pip will create it).

The following is maybe cleaner, but the result is the same: RISE is not enabled:

...
adduser test
su -l test
mkdir -p .local/bin
logout
su -l test  # Log in again: this time .local/bin will be added to the PATH automatically
pip3 install rise
jupyter-notebook

Note that it all works as expected if you install RISE in in a virtualenv environment: rise.json gets installed in venv/etc/jupyter/nbconfig/notebook.d/rise.json. This works because the virtualenv packages are treated as system packages, so installing under etc is fine. So the problem occurs only when installing outside of a virtualenv (in which case the correct path for config files is $HOME/.jupyter/nbconfig/notebook.d).

[damianavila]

@knuesel thanks for the detailed additional information! We should make a note in the docs about this. Labelled accordingly.