Merge pull request #227 from agriyakhetarpal/feat/customise-new-tab-buttons-text

Allow global and custom button text for the new-tabbed variants of the `JupyterLite`, `NotebookLite`, and the `Voici` directives

Author: Carreau

docs/configuration.md

@@ -67,6 +67,23 @@ jupyterlite_config = "jupyter_lite_config.json"
 jupyterlite_overrides = "overrides.json"
 ```
 
+# Setting default button texts for the `JupyterLite`, `NotebookLite`, and `Voici` directives
+
+When using the `:new_tab:` option in the `JupyterLite`, `NotebookLite`, and `Voici` directives,
+the button text defaults to "Open as a notebook" and "Open with Voici", respectively.
+
+You can optionally the button text on a global level for these directives by setting the
+following values in your `conf.py` file:
+
+```python
+jupyterlite_button_text = "My custom JupyterLite button text"
+notebooklite_button_text = "My custom NotebookLite button text"
+voici_button_text = "My custom Voici button text"
+```
+
+You can override this text on a per-directive basis by passing the `:button_text:` option
+to the directive. Note that this is compatible only if `:new_tab:` is also provided.
+
 ## Strip particular tagged cells from IPython Notebooks
 
 When using the `NotebookLite`, `JupyterLite`, or `Voici` directives with a notebook passed to them, you can

docs/directives/jupyterlite.md

@@ -50,6 +50,23 @@ of JupyterLite.
    :new_tab: True
 ```
 
+When using this option, it is also possible to customise the button text, overriding the
+global value using an additional `:button_text:` parameter:
+
+```rst
+.. jupyterlite:: my_notebook.ipynb
+   :new_tab: True
+   :button_text: My custom JupyterLite button text
+```
+
+```{eval-rst}
+.. jupyterlite:: my_notebook.ipynb
+   :new_tab: True
+   :button_text: My custom JupyterLite button text
+```
+
+## Search parameters
+
 The directive `search_params` allows to transfer some search parameters from the documentation URL to the Jupyterlite URL.\
 Jupyterlite will then be able to fetch these parameters from its own URL.\
 For example `:search_params: ["param1", "param2"]` will transfer the parameters *param1* and *param2*.

docs/directives/notebooklite.md

@@ -45,3 +45,18 @@ Lab interface.
 .. notebooklite:: my_notebook.ipynb
    :new_tab: True
 ```
+
+When using this option, it is also possible to customise the button text, overriding the
+global value using an additional `:button_text:` parameter:
+
+```rst
+.. notebooklite:: my_notebook.ipynb
+   :new_tab: True
+   :button_text: My custom NotebookLite button text
+```
+
+```{eval-rst}
+.. notebooklite:: my_notebook.ipynb
+   :new_tab: True
+   :button_text: My custom NotebookLite button text
+```

docs/directives/voici.md

@@ -41,3 +41,17 @@ the notebook in a new browser tab, instead of in the current page.
    :new_tab: True
 ```
 
+When using this option, it is also possible to customise the button text, overriding the
+global value using an additional `:button_text:` parameter:
+
+```rst
+.. voici:: my_notebook.ipynb
+   :new_tab: True
+   :button_text: My custom Voici button text
+```
+
+```{eval-rst}
+.. voici:: my_notebook.ipynb
+   :new_tab: True
+   :button_text: My custom Voici button text
+```

jupyterlite_sphinx/jupyterlite_sphinx.py

@@ -119,6 +119,7 @@ def __init__(
         prefix=JUPYTERLITE_DIR,
         notebook=None,
         lite_options={},
+        button_text=None,
         **attributes,
     ):
         app_path = self.lite_app
@@ -133,6 +134,8 @@ def __init__(
             f'{prefix}/{app_path}{f"index.html?{options}" if options else ""}'
         )
 
+        self.button_text = button_text
+
         super().__init__(
             rawsource,
             **attributes,
@@ -142,7 +145,7 @@ def html(self):
         return (
             '<button class="try_examples_button" '
             f"onclick=\"window.open('{self.lab_src}')\">"
-            "Open as a notebook</button>"
+            f"{self.button_text}</button>"
         )
 
 
@@ -210,6 +213,7 @@ class BaseNotebookTab(_InTab):
 
     lite_app = None
     notebooks_path = None
+    default_button_text = "Open as a notebook"
 
 
 class JupyterLiteTab(BaseNotebookTab):
@@ -295,6 +299,7 @@ def __init__(
         prefix=JUPYTERLITE_DIR,
         notebook=None,
         lite_options={},
+        button_text=None,
         **attributes,
     ):
 
@@ -308,6 +313,8 @@ def __init__(
         # If a notebook is provided, open it in a new tab. Else, we default to the tree view.
         self.lab_src = f'{prefix}/{app_path}{f"?{options}" if options else ""}'
 
+        self.button_text = button_text
+
         super().__init__(
             rawsource,
             **attributes,
@@ -317,7 +324,7 @@ def html(self):
         return (
             '<button class="try_examples_button" '
             f"onclick=\"window.open('{self.lab_src}')\">"
-            "Open with Voici</button>"
+            f"{self.button_text}</button>"
         )
 
 
@@ -380,6 +387,7 @@ class _LiteDirective(SphinxDirective):
         "prompt_color": directives.unchanged,
         "search_params": directives.unchanged,
         "new_tab": directives.unchanged,
+        "button_text": directives.unchanged,
     }
 
     def run(self):
@@ -393,6 +401,8 @@ def run(self):
 
         new_tab = self.options.pop("new_tab", False)
 
+        button_text = None
+
         source_location = os.path.dirname(self.get_source_info()[0])
 
         prefix = os.path.relpath(
@@ -440,6 +450,24 @@ def run(self):
         else:
             notebook_name = None
 
+        if new_tab:
+            directive_button_text = self.options.pop("button_text", None)
+            if directive_button_text is not None:
+                button_text = directive_button_text
+            else:
+                # If none, we use the appropriate global config based on
+                # the type of directive passed.
+                if isinstance(self, JupyterLiteDirective):
+                    button_text = self.env.config.jupyterlite_button_text
+                elif isinstance(self, NotebookLiteDirective):
+                    button_text = self.env.config.notebooklite_button_text
+                elif isinstance(self, VoiciDirective):
+                    button_text = self.env.config.voici_button_text
+        elif "button_text" in self.options:
+            raise ValueError(
+                "'button_text' is only valid if 'new_tab' is True. To modify the prompt text, use 'prompt' and 'prompt_color'."
+            )
+
         if new_tab:
             return [
                 self.newtab_cls(
@@ -451,6 +479,7 @@ def run(self):
                     prompt_color=prompt_color,
                     search_params=search_params,
                     lite_options=self.options,
+                    button_text=button_text,
                 )
             ]
 
@@ -482,6 +511,9 @@ class BaseJupyterViewDirective(_LiteDirective):
         "prompt_color": directives.unchanged,
         "search_params": directives.unchanged,
         "new_tab": directives.unchanged,
+        # "button_text" below is valid only if "new_tab" is True, otherwise
+        # we have "prompt" and "prompt_color" as options already.
+        "button_text": directives.unchanged,
     }
 
 
@@ -895,6 +927,16 @@ def setup(app):
         rebuild="html",
     )
 
+    # Allow customising the button text for each directive (only when "new_tab" is True,
+    # error otherwise)
+    app.add_config_value(
+        "jupyterlite_button_text", "Open as a notebook", rebuild="html"
+    )
+    app.add_config_value(
+        "notebooklite_button_text", "Open as a notebook", rebuild="html"
+    )
+    app.add_config_value("voici_button_text", "Open with Voici", rebuild="html")
+
     # Initialize NotebookLite and JupyterLite directives
     app.add_node(
         NotebookLiteIframe,