Navigating jupyterlab page

docs/_toc.yml

@@ -60,6 +60,8 @@ parts:
     - file: tutorials/r/environments.md
     - file: tutorials/r/slurm.md
   - file: applications/vscode.md
+  - file: tutorials/navigating_jupyterlab.md
+    title: JupyterLab
   - file: applications/other_applications.md
     sections: 
     - file: examples/amber/index.md

docs/tutorials/clone_constellate.md

@@ -0,0 +1,32 @@
+# Digital Humanities Workshop
+
+HPC can support digital humanities research by Ithaka Constellate Notebooks is a platform for learning these techniques without any prior technical experience required. It is currently available as a GitHub repository which can be accessed as a Jupyter workspace containing organized folders and Python files. This page aims to show you how to access the lessons in Jupyter-Lab.
+
+There are also videos dedicated to most of the lessons in the workshop available here: [https://www.youtube.com/@Constellate_org](https://www.youtube.com/@Constellate_org)
+
+1. Start Interactive JupyterLab from the [M3 OnDemand Portal](https://hpc.m3.smu.edu/pun/sys/dashboard/)
+    * Under Select Python Environment, choose one of the following: (M3 Module) python/3.11.11/data_science/2025.04.01 or (M3 Module) python/3.11.11/data_science/2025.08.21
+    * Ignore Custom environment settings
+    * Leave rest settings to default values
+
+![finding Interactive JupyterLab on OnDemand Portal](../images/click_interactive_jupyter-lab.png)
+
+2. Create/choose a place for storing the lessons. This is the parent directory of folder `constellate-notebooks`. The file explorer on the left of Jupyter-Lab is limited to the \$HOME directory; however, one can enter the \$SCRATCH directory by copying and pasting `cd $SCRATCH` to a separate line and then pressing the Enter key.
+
+![choosing parent dir using file explorer on the left](../images/choose_parent_dir.png)
+
+3. Click on Terminal under Other in the Launcher tab. Type the following commands at the end of the latest line in terminal.
+
+![finding the terminal button in the Launcher tab in JupyterLab](../images/click_terminal.jpg)
+
+4. To see the folders and files present in the current directory, type `ls` in a separate line in the Terminal and then press the Enter key.
+
+5. (Optional) To create a new folder in the current directory, type `mkdir DirectoryName` in a separate line in the Terminal, replacing `DirectoryName` with the name you want to give the parent directory and then press the Enter key.
+
+6. Once the path of the chosen parent directory is present before the blinking cursor in the terminal, copy and paste the following command in  a separate line in the Terminal and then press the Enter key.
+    ```
+    git clone https://github.com/SouthernMethodistUniversity/constellate-notebooks.git
+    ```
+    This creates a copy of Constellate Notebooks in your parent directory. The course material is inside a new folder named `constellate-notebooks`.
+
+    To **undo** the cloning process, just right-click and delete the folder with the default name `constellate-notebooks` in the directory you had chosen.

docs/tutorials/navigating_jupyterlab.md

@@ -0,0 +1,85 @@
+# Navigating JupyterLab
+
+JupyterLab is a web-based interface containing a file explorer and a code editor that supports Python, Julia, and various other languages.
+
+## File management
+
+- **To open the Terminal**:
+  - Click the blue button containing a plus sign at the top of the File Browser or the plus sign next to the rightmost tab to open a Launcher tab.
+  - Click on Terminal to create a Terminal tab.
+
+    <img src="../images/navigating_jupyterlab/open_new_terminal.jpg" height="100">
+
+
+- **To open the File Browser**, click the folder icon on the left sidebar.
+
+  <img src="../images/navigating_jupyterlab/open_file_browser.jpg" height="100">
+
+- **To enter a folder**, double-click on it.
+- **To enter a parent directory**, a directory in the path of your location e.g. a folder containing the currently open folder: click on the name of the directory in the path above the column headers in the File Browser.
+
+  <img src="../images/navigating_jupyterlab/enter_parent_directory.jpg" height="100">
+
+- **To upload a file** to the current location, click on the upload icon above the path.
+
+  <img src="../images/navigating_jupyterlab/upload.jpg" height="100">
+
+- **To delete, rename, etc. a file**, right-click on a file or directory.
+- **To paste copied file(s)**, right-click anywhere under the column header, then click Paste.
+
+  <img src="../images/navigating_jupyterlab/paste_file.jpg" height="100">
+
+- **To open project directories** located outside your home directory (/$HOME or users/username) in the File Browser, you will need to create a symlink.
+  - Click the plus sign at the top of the File Browser to open a new Launcher tab.
+  - Click the Terminal button to open a new Terminal tab.
+  - Copy and paste `ln -s "<project directory>" ~/<new directory name>` into the Terminal, replacing `<project directory>` with the path of your project directory and `/<new directory name>` with the desired position of the link in your $HOME directory. Press Enter.
+  - Navigate to the path of the symlink. Click the refresh button in the top right corner of the File Browser if required.
+
+      <img src="../images/navigating_jupyterlab/refresh.jpg" height="100">
+
+  - The project directory can now be opened in the File Browser by double clicking the symlink.
+
+## Code editing
+
+Jupyter contains cells that can be run individually. These cells can run either markdown or the language of the Kernel visible in top right corner of a .ipynb document tab. Python3 comes already installed with JupyterLab. Cells can also contain Magic Commands that are outside the standard functionality of Python.
+- **To open a new notebook**:
+  - Click the plus sign next to the currently open tab on the right side of JupyterLab in case there isn't a Launcher tab already open.
+
+    <img src="../images/navigating_jupyterlab/open_launcher.jpg" height="100">
+
+  - In the Launcher tab, click on the desired kernel type under Notebook to open a new notebook.
+
+    <img src="../images/navigating_jupyterlab/open_new_notebook.jpg" height="100"> 
+
+- **Run options** can be chosen by clicking the 'Run' tab in line with the Jupyter logo at the top, then clicking the desired run option.
+
+    <img src="../images/navigating_jupyterlab/run_options.jpg" height="100">
+
+- **To save or create a new checkpoint**, click on the memory card icon under the .ipynb tab or simultaneously press the Ctrl and S keys.
+
+    <img src="../images/navigating_jupyterlab/save.jpg" height="100">
+
+- **Cell operations** like creating cells, copying them, etc. can be done by clicking on the 'Edit' tab in line with the Jupyter logo at the top, and then clicking the desired operation. 
+
+    <img src="../images/navigating_jupyterlab/cell_operations.jpg" height="100">
+
+- **To open a new Python file**, open the Launcher tab, then click on Python File under Other.
+
+  <img src="../images/navigating_jupyterlab/open_new_Python_file.jpg" height="100">
+
+- **To run a Python file**:
+  - Method 1:
+    - Open a Terminal.
+    - Type `python path_to_py_file`, replacing `path_to_py_file` with the path to the Python file.
+    - Press Enter. The output is displayed within the Terminal.
+  - Method 2:
+    - Open a notebook.
+    - Copy and paste the following in a separate line of a cell, replacing `path_to_py_file` with the relative path to the Python file:
+      ```
+      %run path_to_py_file
+      ```
+    - Run the cell. The output for the Python file is displayed under the cell.
+
+
+## Additional Help
+[This website](https://jupyterlab.readthedocs.io/en/latest/user/notebook.html) contains in-depth instructions on navigating JupyterLab Notebooks.