From a71b7181c02f9b9e6618e1066202f38f11d70ef5 Mon Sep 17 00:00:00 2001 From: Jeremy Tuloup Date: Thu, 23 Jun 2022 23:15:22 +0200 Subject: [PATCH] DOC: Add an interactive shell powered by JupyterLite to the website (#47428) * Add an interactive shell powered by JupyterLite * Update to the dedicated JupyterLite deployment * Add example code * Move build files to the pandas repo * Build the jupyterlite website * Load relative terminal * Update example code * Update wording * Fix trailing spaces * Move build dependencies to the top-level environment.yml * Move to `web/interactive_terminal` * Remove example code * Add note about the loading time * Update instructions in the README * Update build command on CI * Fix typo in .gitignore * Lint environment.yml * Remove unused import * Undo unrelated changes in environment.yml * Fix pre-commit check * Remove unused csv file --- .github/workflows/docbuild-and-upload.yml | 5 +++ .gitignore | 4 +++ environment.yml | 5 +++ requirements-dev.txt | 2 ++ web/interactive_terminal/README.md | 35 +++++++++++++++++++ web/interactive_terminal/jupyter-lite.json | 13 +++++++ .../jupyter_lite_config.json | 7 ++++ web/pandas/getting_started.md | 13 +++++++ 8 files changed, 84 insertions(+) create mode 100644 web/interactive_terminal/README.md create mode 100644 web/interactive_terminal/jupyter-lite.json create mode 100644 web/interactive_terminal/jupyter_lite_config.json diff --git a/.github/workflows/docbuild-and-upload.yml b/.github/workflows/docbuild-and-upload.yml index 5ffd4135802bd..f9a941b87387c 100644 --- a/.github/workflows/docbuild-and-upload.yml +++ b/.github/workflows/docbuild-and-upload.yml @@ -46,6 +46,11 @@ jobs: - name: Build documentation run: doc/make.py --warnings-are-errors + - name: Build the interactive terminal + run: | + cd web/interactive_terminal + jupyter lite build + - name: Install ssh key run: | mkdir -m 700 -p ~/.ssh diff --git a/.gitignore b/.gitignore index 87224f1d6060f..07b1f056d511b 100644 --- a/.gitignore +++ b/.gitignore @@ -122,3 +122,7 @@ doc/build/html/index.html doc/tmp.sv env/ doc/source/savefig/ + +# Interactive terminal generated files # +######################################## +.jupyterlite.doit.db diff --git a/environment.yml b/environment.yml index 98631d8485736..0a6055d80c071 100644 --- a/environment.yml +++ b/environment.yml @@ -123,3 +123,8 @@ dependencies: - feedparser - pyyaml - requests + + # build the interactive terminal + - jupyterlab >=3.4,<4 + - pip: + - jupyterlite==0.1.0b9 diff --git a/requirements-dev.txt b/requirements-dev.txt index 2b8aee80882a5..f5dfeb8e7ff30 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -96,4 +96,6 @@ markdown feedparser pyyaml requests +jupyterlab >=3.4,<4 +jupyterlite==0.1.0b9 setuptools>=51.0.0 diff --git a/web/interactive_terminal/README.md b/web/interactive_terminal/README.md new file mode 100644 index 0000000000000..865cf282676c9 --- /dev/null +++ b/web/interactive_terminal/README.md @@ -0,0 +1,35 @@ +# The interactive `pandas` terminal + +An interactive terminal to easily try `pandas` in the browser, powered by JupyterLite. + +![image](https://user-images.githubusercontent.com/591645/175000291-e8c69f6f-5f2c-48d7-817c-cff05ab2cde9.png) + +## Build + +The interactive terminal is built with the `jupyterlite` CLI. + +First make sure `jupyterlite` is installed: + +```bash +python -m pip install jupyterlite +``` + +Then in `web/interactive_terminal`, run the following command: + +```bash +jupyter lite build +``` + +## Configuration + +This folder contains configuration files for the interactive terminal powered by JupyterLite: + +- `jupyter_lite_config.json`: build time configuration, used when building the assets with the `jupyter lite build` command +- `jupyter-lite.json` run time configuration applied when launching the application in the browser + +The interactive `pandas` terminal application enables a couple of optimizations to only include the `repl` app in the generated static assets. +To learn more about it, check out the JupyterLite documentation: + +- Optimizations: https://jupyterlite.readthedocs.io/en/latest/howto/configure/advanced/optimizations.html +- JupyterLite schema: https://jupyterlite.readthedocs.io/en/latest/reference/schema-v0.html +- CLI reference: https://jupyterlite.readthedocs.io/en/latest/reference/cli.html diff --git a/web/interactive_terminal/jupyter-lite.json b/web/interactive_terminal/jupyter-lite.json new file mode 100644 index 0000000000000..473fb5a3dcc1a --- /dev/null +++ b/web/interactive_terminal/jupyter-lite.json @@ -0,0 +1,13 @@ +{ + "jupyter-lite-schema-version": 0, + "jupyter-config-data": { + "appName": "Pandas REPL", + "appUrl": "./repl", + "disabledExtensions": [ + "@jupyter-widgets/jupyterlab-manager" + ], + "enableMemoryStorage": true, + "settingsStorageDrivers": ["memoryStorageDriver"], + "contentsStorageDrivers": ["memoryStorageDriver"] + } + } diff --git a/web/interactive_terminal/jupyter_lite_config.json b/web/interactive_terminal/jupyter_lite_config.json new file mode 100644 index 0000000000000..8a8c4eb1ae051 --- /dev/null +++ b/web/interactive_terminal/jupyter_lite_config.json @@ -0,0 +1,7 @@ +{ + "LiteBuildConfig": { + "apps": ["repl"], + "no_unused_shared_packages": true, + "output_dir": "../build/lite" + } + } diff --git a/web/pandas/getting_started.md b/web/pandas/getting_started.md index d4f40a1153fb4..dc43a6a273832 100644 --- a/web/pandas/getting_started.md +++ b/web/pandas/getting_started.md @@ -1,5 +1,18 @@ # Getting started +## Try it in your browser + +You can try `pandas` in your browser with the following interactive shell +without installing anything on your computer. + +*Note it can take up to 30 seconds before the shell finishes loading and is ready to run commands.* + + + ## Installation instructions The next steps provides the easiest and recommended way to set up your