add read only flag

README.md

@@ -1,8 +1,12 @@
-# jupyter_stack_trace
+# Jupyter Stack Trace
 
 [![Github Actions Status](https://github.com/teticio/jupyter-stack-trace/workflows/Build/badge.svg)](https://github.com/teticio/jupyter-stack-trace/actions/workflows/build.yml)
 A JupyterLab extension to jump to the line in the file of the stack trace.
 
+(Migrated from https://github.com/teticio/nbextension-gotoerror to JupyterLab and Jupyter Notebook 7.)
+
+One of the disadvantages of working with Jupyter Notebooks is that they can be very difficult to debug when something goes wrong deep down in a stack trace. This extension allows you to click on any of the items in the stack trace and opens up the relevant file at the line where the error occured. A button is also added which searches Google for the error in Stack Overflow.
+
 ## Requirements
 
 - JupyterLab >= 4.0.0
@@ -23,6 +27,28 @@ To remove the extension, execute:
 pip uninstall jupyter_stack_trace
 ```
 
+## Settings
+
+Jupyter is only able to access files in the directory in which it is run or a subdirectory. Therefore, to be able to open a file in the stack trace, it is necessary to provide a soft link from the Jupyter launch directory to package source directories.
+
+Make a soft link in the Jupyter launch directory to a base directory of your Python instalation (e.g., `~/.local/lib/python3.10`) and call this `python3.10`. Then add the prefix `~/.local/lib` in the `jupyter-stack-trace` settings. If you use `pipenv`, for example, then also make a soft link to the `~/.local/share/virtualenvs` called `virtualenvs` and add the prefix `~/.local/share`.
+
+The exact configuration will depend on your setup, but if you find that clicking a filename in the stack trace does not open up the file, then make the soft link to a point somewhere higher up the path and add the corresponding prefix in the settings.
+
+To make a soft link in Linux:
+
+```bash
+ln -s ~/.local/lib/python3.10 python3.10
+```
+
+To make a soft link in Windows:
+
+```cmd
+mklink -d envs C:\users\teticio\Anaconda\python\envs
+```
+
+By default, files are opened as read only, but you can override this in the settings. This allows you to directly modify the packages so you can add temporary debugging code.
+
 ## Contributing
 
 ### Development install

schema/plugin.json

@@ -1,17 +1,23 @@
 {
   "jupyter.lab.shortcuts": [],
   "title": "jupyter-stack-trace",
-  "description": "jupyter-stack-trace settings.",
+  "description": "Make a soft link in the Jupyter launch directory to the a base directory of your Python instalation (e.g., ~/.local/lib/python3.10) and call this python3.10. Then add the prefix ~/.local/lib in the jupyter-stack-trace settings. See https://github.com/teticio/jupyter-stack-trace for more details.",
   "type": "object",
   "properties": {
     "prefixes": {
       "title": "Prefixes",
-      "description": "Array of string prefixes.",
+      "description": "Prefixes to your Python environments.",
       "type": "array",
       "items": {
         "type": "string"
       },
       "default": []
+    },
+    "readOnly": {
+      "title": "Read only",
+      "description": "If true, files are opened as read only.",
+      "type": "boolean",
+      "default": true
     }
   },
   "additionalProperties": false

src/index.ts

@@ -31,12 +31,15 @@ const plugin: JupyterFrontEndPlugin<void> = {
     console.log('JupyterLab extension jupyter-stack-trace is activated!');
 
     let prefixes: string[] = [];
+    let readOnly = true;
+
     if (settingRegistry) {
       settingRegistry
         .load(plugin.id)
         .then(settings => {
           console.log('jupyter-stack-trace settings loaded:', settings.composite);
           prefixes = settings.get('prefixes').composite as string[];
+          readOnly = settings.get('readOnly').composite as boolean;
         })
         .catch(reason => {
           console.error('Failed to load settings for jupyter-stack-trace.', reason);
@@ -61,7 +64,7 @@ const plugin: JupyterFrontEndPlugin<void> = {
                 const editor = (widget.content as FileEditor).editor;
                 let line_number = Number(line) || 1;
 
-                editor.setOption('readOnly', true);
+                editor.setOption('readOnly', readOnly);
                 editor.setCursorPosition({ line: line_number - 1, column: 0 });
                 editor.setSelection({
                   start: { line: line_number - 1, column: 0 },
@@ -89,7 +92,7 @@ const plugin: JupyterFrontEndPlugin<void> = {
           cell.model.outputs.add({
             output_type: 'display_data',
             data: {
-              'text/html': '<br><button class="stack-trace-stackoverflow-btn" onclick="window.open(\'' + url + '\', \'_blank\');">Search Stack Overflow</button>'
+              'text/html': '<br><button class="stack-trace-stack-overflow-btn" onclick="window.open(\'' + url + '\', \'_blank\');">Search Stack Overflow</button>'
             }
           });
         }

style/base.css

@@ -8,7 +8,7 @@ span.ansi-green-fg {
     cursor: pointer;
 }
 
-.stack-trace-stackoverflow-btn {
+.stack-trace-stack-overflow-btn {
     border: 0;
     font-size: 11px;
     margin: 0px 4px;
@@ -19,6 +19,6 @@ span.ansi-green-fg {
     user-select: none;
 }
 
-.stack-trace-stackoverflow-btn:hover {
+.stack-trace-stack-overflow-btn:hover {
     background-color: #e0e0e0;
-}
+}