Add more REPL customisation features for JupyterLite 0.6.0 (DO NOT MERGE)

dev-environment.yml

@@ -5,7 +5,6 @@ dependencies:
     - pip
     - jupyter_server
     - jupyterlab_server
-    - jupyterlite-core >=0.3,<0.6
     - jupytext
     - pydata-sphinx-theme
     - micromamba=2.0.5
@@ -16,4 +15,5 @@ dependencies:
     - voici
     - pip:
         - .
-        - jupyterlite-xeus >=2.1.2
+        - jupyterlite-core ==0.6.0a9
+        # - jupyterlite-xeus >=2.1.2

docs/configuration.md

@@ -85,11 +85,50 @@ voici_new_tab_button_text = "My custom Voici button text"
 You can override this text on a per-directive basis by passing the `:new_tab_button_text:` option
 to the directive. Note that this is compatible only if `:new_tab:` is also provided.
 
-## REPL code auto-execution with the `Replite` directive
+## REPL configuration options
 
-It is possible to control whether code snippets in REPL environments automatically executes when loaded.
-For this, you may set `replite_auto_execute = False` globally in `conf.py` with  (defaults to `True` if
-not present), or override it on a per-directive basis  with `:execute: True` or `:execute: False`.
+We provide several configuration options for the Replite directive that control the behaviour and appearance of the REPL. These options can be set globally in `conf.py` and then overridden on a per-directive basis.
+
+### REPL code auto-execution
+
+```python
+# enable or disable automatic code execution when the REPL loads
+# (available in jupyterlite-core 0.5.0 and later)
+replite_auto_execute = True  # default is True
+```
+
+This setting controls whether code snippets in REPL environments automatically execute when loaded. Set to `False` to disable automatic execution. You can override this on a per-directive basis with `:execute: True` or `:execute: False`.
+
+### REPL interface customisations (JupyterLite 0.6.0 and later)
+
+The following options customise how the REPL interface behaves and is presented:
+
+```python
+# clear previous cells when a new cell is executed
+replite_clear_cells_on_execute = False  # default is False
+
+# clear the code content in the prompt cell after execution
+replite_clear_code_content_on_execute = False  # default is False
+
+# hide input cells, showing only output
+replite_hide_code_input = False  # default is False
+
+# position of the prompt cell ('bottom', 'top', 'left', or 'right')
+replite_prompt_cell_position = "bottom"  # default is "bottom"
+
+# show or hide the kernel banner
+replite_show_banner = True  # default is True
+```
+
+These global settings can be overridden in individual directives using the corresponding options:
+
+- `:clear_cells_on_execute: True/False`
+- `:clear_code_content_on_execute: True/False`
+- `:hide_code_input: True/False`
+- `:prompt_cell_position: bottom/top/left/right`
+- `:show_banner: True/False`
+
+For more details and visual examples of each, see the [Replite directive documentation](directives/replite.md).
 
 ## Strip particular tagged cells from IPython Notebooks
 
@@ -120,7 +159,7 @@ Sphinx-specific content. It can be used to remove either code cells or Markdown
 For example, you can use this feature to remove the `toctree` directive from the rendered notebook
 in the JupyterLite console:
 
-```json
+````json
 {
   "cells": [
     {
@@ -148,7 +187,7 @@ in the JupyterLite console:
     }
   ]
 }
-```
+````
 
 where the cell with the `toctree` directive will be removed from the rendered notebook in
 the JupyterLite console.

docs/directives/replite.md

@@ -157,3 +157,173 @@ global value using an additional `:new_tab_button_text:` parameter:
 ```
 
 ````
+
+````{tip}
+
+   ## Additional REPL interface options (JupyterLite 0.6.0+)
+
+   With `jupyterlite-core` versions 0.6.0 and later, the REPL interface comes with several additional customisation options that provide more control over the execution environment and layout:
+
+   ### Clearing cells on execute
+
+   To automatically clear the previously executed cells when a new cell is executed, use the `:clear_cells_on_execute:` option:
+
+   ```rst
+   .. replite::
+      :kernel: xeus-python
+      :clear_cells_on_execute: True
+
+      # When you execute this cell and then enter new code,
+      # this cell will disappear from the display
+      print("Hello, world!")
+   ```
+
+   ```{eval-rst}
+   .. replite::
+      :kernel: xeus-python
+      :clear_cells_on_execute: True
+
+      # When you execute this cell and then enter new code,
+      # this cell will disappear from the display
+      print("Hello, world!")
+   ```
+
+   ### Clearing code content on execute
+
+   To automatically clear the code content in the prompt cell after execution, use the `:clear_code_on_execute:` option:
+
+   ```rst
+   .. replite::
+      :kernel: xeus-python
+      :clear_code_content_on_execute: True
+
+      # After executing this cell, its content will be cleared,
+      # but the output will remain visible
+      print("The code will disappear but this output stays")
+   ```
+
+   ```{eval-rst}
+   .. replite::
+      :kernel: xeus-python
+      :clear_code_content_on_execute: True
+
+      # After executing this cell, its content will be cleared,
+      # but the output will remain visible
+      print("The code will disappear but this output stays")
+   ```
+
+   ### Hiding code input
+
+   To hide the input cells after execution, showing only the output, use the `:hide_code_input:` option:
+
+   ```rst
+   .. replite::
+      :kernel: xeus-python
+      :hide_code_input: True
+
+      # After executing this cell, the input will be hidden,
+      # but the output will remain visible
+      print("You'll see this output but not the code that generated it")
+   ```
+
+   ```{eval-rst}
+   .. replite::
+      :kernel: xeus-python
+      :hide_code_input: True
+
+      # After execution, this code will be hidden
+      # Only the output will be visible
+      print("You'll see this output but not the code that generated it")
+   ```
+
+   ### Changing prompt cell position
+
+   By default, the prompt cell is positioned at the bottom of the REPL interface. You can change this using the `:prompt_cell_position:` option, which accepts `top`, `bottom`, `left`, or `right`:
+
+   ```rst
+   .. replite::
+      :kernel: xeus-python
+      :prompt_cell_position: top
+
+      # The prompt will appear at the top of the REPL
+      print("Input above, output below")
+   ```
+
+   ```{eval-rst}
+   .. replite::
+      :kernel: xeus-python
+      :prompt_cell_position: top
+
+      # The prompt will appear at the top of the REPL
+      print("Input above, output below")
+   ```
+
+   ### Showing or hiding the kernel banner
+
+   By default, the REPL shows the kernel banner with version information. To hide this banner, use the `:show_banner:` option:
+
+   ```rst
+   .. replite::
+      :kernel: xeus-python
+      :show_banner: False
+
+      # The kernel banner won't be displayed
+      print("No banner here")
+   ```
+
+   ```{eval-rst}
+   .. replite::
+      :kernel: xeus-python
+      :show_banner: False
+
+      # The kernel banner won't be displayed
+      print("No banner here")
+   ```
+
+   ### Combining options
+   All of these options can be combined to create a customised REPL experience,
+   for example:
+
+   ```rst
+   .. replite::
+      :kernel: xeus-python
+      :prompt_cell_position: left
+      :hide_code_input: True
+      :show_banner: False
+      :height: 400px
+
+      # This will create a clean output-only display
+      # with the input cell on the left
+      import matplotlib.pyplot as plt
+      import numpy as np
+
+      x = np.linspace(0, 2 * np.pi, 200)
+      y = np.sin(x)
+
+      fig, ax = plt.subplots()
+      ax.plot(x, y)
+      plt.show()
+   ```
+
+   ```{eval-rst}
+   .. replite::
+      :kernel: xeus-python
+      :prompt_cell_position: left
+      :hide_code_input: True
+      :show_banner: False
+      :height: 400px
+
+      # This will create a clean output-only display
+      # with the input cell on the left
+      import matplotlib.pyplot as plt
+      import numpy as np
+
+      x = np.linspace(0, 2 * np.pi, 200)
+      y = np.sin(x)
+
+      fig, ax = plt.subplots()
+      ax.plot(x, y)
+      plt.show()
+   ```
+
+````