Merge pull request #1154 from mahendrapaipuri/jlab_frontend_extension

* feat: Create text notebook from lab interface

- Users should be able to create text notebooks in different formats

- Launcher icons have been added to create text notebooks

- Existing extension code has been refactored to split into logical files

* feat: Add jupytext menu

- A dedicated Jupytext menu has been added to launch text notebooks

* feat: Update npm dependencies

- Add dependencies needed for launching text notebooks

* feat: Modify contentsManager

- Check properly if asked model is of jupytext or native format

- Add few tests to ensure that jupytext contentsManager is creating files properly

* build: Add a custom script to develop extension

- Repo organization does not permit to use native jupyterlab script

- Small utility script has been added to create symlink of extension data
while in dev mode

* test: Add basic integration tests

- Galata UI tests have been added to check jupytext extension

* test: Add reference screenshots for UI tests

* style: Fix Lint errors

* test: Use a pixel tolerance on screenshot comparison

- Comparing colors can be a bit flaky given colors can vary across platforms

- We use a maxDiffPixelRatio to smooth these issues out of tests

* ci: Add integration tests for extension

* refactor: Revert to original implementation

* test: Improve test cases for contents manager

* feat: Make jupytext extension confgurable

- Users will be able to configure category of Text notebooks in launcher

- Users can configure which formats should be added to launcher

- These configs will be available via Settings in JupyterLab

* docs: Update instructions on extension development

* test: Update integration tests

* docs: Add a section about extension in docs

* style: Fix pre-commit issues

* test: Remove duplicated snapshots for ui tests

.github/workflows/ci.yml

@@ -9,12 +9,12 @@ on:
         description: Upload build artifacts
   push:
     paths-ignore:
-      - 'CHANGELOG.md'
-    branches: [ main ]
+      - "CHANGELOG.md"
+    branches: [main]
   pull_request:
-    branches: [ main ]
+    branches: [main]
   schedule:
-    - cron: '0 11 * * 4'
+    - cron: "0 11 * * 4"
 
 permissions:
   # All nested workflows will inherit these permissions and so no need to declare
@@ -34,25 +34,29 @@ jobs:
     uses: ./.github/workflows/step_pre-commit.yml
 
   codeql:
-    needs: [ pre-commit ]
+    needs: [pre-commit]
     uses: ./.github/workflows/step_static-analysis.yml
 
   test-pip:
-    needs: [ codeql ]
+    needs: [codeql]
     uses: ./.github/workflows/step_tests-pip.yml
 
   test-conda:
-    needs: [ codeql ]
+    needs: [codeql]
     uses: ./.github/workflows/step_tests-conda.yml
 
+  test-ui:
+    needs: [codeql]
+    uses: ./.github/workflows/step_tests-ui.yml
+
   build:
-    needs: [ test-pip, test-conda ]
+    needs: [test-pip, test-conda, test-ui]
     uses: ./.github/workflows/step_build.yml
     with:
       upload: ${{ inputs.upload-build-artifacts || false }}
 
   pass:
-    needs: [ pre-commit, codeql, test-pip, test-conda, build ]
+    needs: [pre-commit, codeql, test-pip, test-conda, test-ui, build]
     runs-on: ubuntu-latest
     steps:
       - name: Check jobs

.github/workflows/step_tests-ui.yml

@@ -0,0 +1,46 @@
+name: test-ui
+run-name: Run UI tests with Galata
+
+on:
+  workflow_call:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}-ui-test
+  cancel-in-progress: true
+
+jobs:
+  test-ui:
+    continue-on-error: false
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Base Setup
+        uses: jupyterlab/maintainer-tools/.github/actions/base-setup@v1
+
+      - name: Install from source (required for the pre-commit tests)
+        run: python -m pip install -e '.[test-cov]'
+
+      - name: Install galata
+        working-directory: jupyterlab/packages/jupyterlab-jupytext-extension/ui-tests
+        env:
+          PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: 1
+        run: jlpm install
+
+      - name: Install browser
+        working-directory: jupyterlab/packages/jupyterlab-jupytext-extension/ui-tests
+        run: jlpm playwright install chromium
+
+      - name: Integration tests
+        working-directory: jupyterlab/packages/jupyterlab-jupytext-extension/ui-tests
+        run: jlpm playwright test
+
+      - name: Upload UI Test artifacts
+        if: failure()
+        uses: actions/upload-artifact@v3
+        with:
+          name: ui-test-output
+          path: |
+            jupyterlab/packages/jupyterlab-jupytext-extension/ui-tests/test-results

docs/index.md

@@ -10,6 +10,7 @@
 install.md
 text-notebooks.md
 paired-notebooks.md
+jupyterlab-extension.md
 config.md
 advanced-options.md
 formats-scripts.md

docs/jupyterlab-extension.md

@@ -0,0 +1,31 @@
+# Frontend extension
+
+Recent versions of Jupytext (`>=1.16.0`) ships frontend extension that enables users
+to create text notebooks and pair notebooks from main menu of JupyterLab 4 and
+Notebook 7. In addition, the frontend extension adds selected Jupytext text
+notebook formats to launcher in the `Jupytext` section so that users can launch text
+notebooks as they launch a regular notebook from JupyterLab launcher.
+
+## Launcher icons
+
+After installing Jupytext extension, users will have a new category in the launcher
+called Jupytext as shown below:
+
+![](images/jupyterlab_launcher.png)
+
+Users can remove and/or add new formats to the Jupytext section _via_ `Settings>Jupytext`.
+
+![](images/jupyterlab_settings.png)
+
+By clicking `Add` and adding a new format, say `qmd`, will
+add the Quatro Text Notebook to the launcher. **Note** that users need to refresh the current browser tab when they modify the settings for them to take effect.
+
+Besides, users can also change the category of Text Notebook launcher icons using
+`Category` field in the Settings. For example, by using `Notebook` as category, all
+Text Notebook launchers will be moved into `Notebook` category.
+
+## Main menu
+
+It is also possible to launch text notebooks and/or pair existing notebooks from the dedicated Jupytext main menu as shown below.
+
+![](images/jupyterlab_main_menu.png)

jupyterlab/.gitignore

@@ -25,3 +25,7 @@ lib/
 *.egg-info/
 .ipynb_checkpoints
 *.tsbuildinfo
+
+# Ignore playwright stuff
+**/playwright-report
+**/test-results

jupyterlab/package.json

@@ -61,7 +61,7 @@
         ],
         "parser": "@typescript-eslint/parser",
         "parserOptions": {
-            "project": "tsconfig.eslint.json",
+            "project": "packages/**/tsconfig.json",
             "sourceType": "module",
             "tsconfigRootDir": "."
         },

jupyterlab/packages/jupyterlab-jupytext-extension/README.md

@@ -23,15 +23,33 @@ jupyter labextension install jupyterlab-jupytext@1.1.1  # for JupyterLab 1.x
 
 # How to develop this extension
 
-Please follow the instructions at [developing.md](../../../docs/developing.md), i.e.
-create a Python environment with a recent version of `nodejs`, and install
-a development version of Jupytext by running
+For fine-grained access to the `jlpm` command and various build steps:
 
 ```bash
 pip install -e '.[dev]'
+cd jupyterlab/packages/jupyterlab-jupytext
+jlpm
+jlpm install:extension     # Symlink into `{sys.prefix}/share/jupyter/labextensions`
 ```
 
-at the root of the Jupytext repository.
+(see also the instructions at [developing.md](../../../docs/developing.md) on how to create a Python environment with a recent version of `nodejs`)
+
+Watch the source directory and automatically rebuild the `lib` folder:
+
+```bash
+cd jupyterlab/packages/jupyterlab-jupytext
+# Watch the source directory in one terminal, automatically rebuilding when needed
+jlpm watch
+# Run JupyterLab in another terminal
+jupyter lab
+```
+
+While running `jlpm watch`, every saved change to a `.ts` file will immediately be
+built locally and available in your running Jupyter client. "Hard" refresh JupyterLab or Notebook
+with <kbd>CTRL-F5</kbd> or <kbd>⌘-F5</kbd> to load the change in your browser
+(you may need to wait several seconds for the extension to be fully rebuilt).
+
+Read more on this on the [JupyterLab documentation](https://jupyterlab.readthedocs.io/en/latest/extension/extension_dev.html#developing-a-prebuilt-extension).
 
 # How to publish a new version of the extension on npm
 

jupyterlab/packages/jupyterlab-jupytext-extension/package.json

@@ -24,6 +24,9 @@
     "type": "git",
     "url": "https://github.com/mwouts/jupytext.git"
   },
+  "workspaces": [
+    "ui-tests"
+  ],
   "scripts": {
     "build": "jlpm run build:lib && jlpm run build:labextension:dev && jlpm run copy:extensioncfgfile",
     "build:labextension": "jupyter labextension build .",
@@ -35,7 +38,7 @@
     "clean:all": "jlpm run clean:lib && jlpm run clean:labextension",
     "clean:labextension": "rimraf ../../jupyterlab_jupytext/labextension",
     "clean:lib": "rimraf lib tsconfig.tsbuildinfo",
-    "install:extension": "jupyter labextension develop --overwrite .",
+    "install:extension": "python ../../scripts/install_extension.py",
     "watch": "run-p watch:src watch:labextension",
     "watch:labextension": "jupyter labextension watch .",
     "watch:src": "tsc -w"
@@ -65,18 +68,23 @@
     "@jupyterlab/application": "^4.0.0",
     "@jupyterlab/apputils": "^4.0.0",
     "@jupyterlab/codeeditor": "^4.0.0",
+    "@jupyterlab/docregistry": "^4.0.0",
+    "@jupyterlab/filebrowser": "^4.0.0",
+    "@jupyterlab/launcher": "^4.0.0",
     "@jupyterlab/nbformat": "^4.0.0",
     "@jupyterlab/notebook": "^4.0.0",
     "@jupyterlab/rendermime": "^4.0.0",
     "@jupyterlab/settingregistry": "^4.0.0",
     "@jupyterlab/translation": "^4.0.0",
     "@jupyterlab/ui-components": "^4.0.0",
+    "@lumino/coreutils": "^2.0.0",
+    "@lumino/disposable": "^2.0.0",
     "jupyterlab-rise": "^0.41.0"
   },
   "devDependencies": {
     "@jupyterlab/builder": "^4.0.0",
     "npm-run-all": "^4.1.5",
-    "rimraf": "^3.0.2",
-    "typescript": "~5.0.1"
+    "rimraf": "^4.4.1",
+    "typescript": "~5.0.2"
   }
 }