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

README enhancement : Clarify "terminal" #94

Open
TonyGravagno opened this issue Mar 17, 2024 · 0 comments
Open

README enhancement : Clarify "terminal" #94

TonyGravagno opened this issue Mar 17, 2024 · 0 comments

Comments

@TonyGravagno
Copy link

From README :

Please make sure tslab command is available in your terminal.

tslab install --version
Then, register tslab to your Jupyter environment.
tslab install [--python=python3]

There's nothing above this to indicate which "terminal" we need to be in. If we are in Unix/Linux shell or in Windows "cmd" using any other common "terminal" application, the version check will succeed, but the install will fail :

Running python C:..path..\npm\node_modules\tslab\python\install.py --tslab=tslab.cmd
jupyter is not installed in this Python.

Then :

After you run tslab install, please check two kernels (jslab and tslab) are installed properly to jupyter.
$ jupyter kernelspec list

Since the jupyter command isn't in the local path, this command also fails.

To use those commands, we need to be in a Jupyter / JupyterLab Terminal, not a common "terminal/shell/cmd" window. To a newcomer (me), this isn't obvious, especially since npm and the tslab version check work from outside of Jupyter. The Jupyter Terminal opens to the defined Work folder with a local Python env/environment setup. This includes the "jupyter" script, so the install and kernelspec list work.

The above is further complicated when the README says: "After you register tslab to Jupyter, start JupyterLab and Jupyter Notebook as usual." If the reader is confused about which terminal to use, this seems to imply that Jupyter might not be opened yet, and it needs to be opened after tslab is registered. That's not correct.

Suggested enhancement:

Prerequisites

  • Open your installation of JupyterLab or Jupyter Notebook
    • From menu File>New, open a new Terminal. All commands below must be executed from this terminal.

Adding that to the existing list of prerequisites should ensure commands are executed in the correct environment.

However, that also implies that a Python environment is defined. I don't know if an env_1 or similar environment needs to be defined in a new JupyterLab installation, or if Terminal will open to the bundled environment. The suggestion may need to be modified to tell the user that they need to define an environment before opening the Terminal.

Finally, the $ jupyter kernelspec list instruction shows the command shell as "$", a non-root BASH. None of the other commands include the shell prompt. I suggest removing the "$" just for consistency, and especially since Windows users have different prompts (whether cmd or PowerShell.
While this is a separate issue from the above notes about the terminal, I'm including this in this ticket because it's just a one character change and it doesn't make sense to open a new ticket for it.

Thanks.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant