diff --git a/dev-environment.yml b/dev-environment.yml index 2547bde..582813c 100644 --- a/dev-environment.yml +++ b/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 diff --git a/docs/configuration.md b/docs/configuration.md index 3774fb9..10221c8 100644 --- a/docs/configuration.md +++ b/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. diff --git a/docs/directives/replite.md b/docs/directives/replite.md index 26f115f..33015ed 100644 --- a/docs/directives/replite.md +++ b/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() + ``` + +```` diff --git a/jupyterlite_sphinx/jupyterlite_sphinx.py b/jupyterlite_sphinx/jupyterlite_sphinx.py index 989a739..98a35b2 100644 --- a/jupyterlite_sphinx/jupyterlite_sphinx.py +++ b/jupyterlite_sphinx/jupyterlite_sphinx.py @@ -85,7 +85,7 @@ def html(self): ) placeholder_id = uuid4() - container_style = f'width: {self["width"]}; height: {self["height"]};' + container_style = f"width: {self['width']}; height: {self['height']};" return f"""
=0.2,<0.6", + "jupyterlite-core==0.6.0a9", "jupytext", "nbformat", "sphinx>=4", @@ -30,7 +30,7 @@ dev = [ docs = [ "myst_parser", "pydata-sphinx-theme", - "jupyterlite-xeus>=0.1.8,<4", + # "jupyterlite-xeus>=0.1.8,<4", ] [tool.hatch.version]