From 103a9fd3930814671e975cd691a666046abe5256 Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Fri, 29 Mar 2024 02:13:52 +0530 Subject: [PATCH 01/12] Use `try_examples_global_button_text` if not `None` --- jupyterlite_sphinx/jupyterlite_sphinx.py | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/jupyterlite_sphinx/jupyterlite_sphinx.py b/jupyterlite_sphinx/jupyterlite_sphinx.py index dcb3feb..df146a9 100644 --- a/jupyterlite_sphinx/jupyterlite_sphinx.py +++ b/jupyterlite_sphinx/jupyterlite_sphinx.py @@ -380,7 +380,13 @@ def run(self): directive_key ) - button_text = self.options.pop("button_text", "Try it with Jupyterlite!") + # Use button_text from try_examples_global_button_text if not provided + if self.env.config.try_examples_global_button_text is not None: + button_text = self.options.pop( + "button_text", self.env.config.try_examples_global_button_text + ) + else: + button_text = self.options.pop("button_text", "Try it with JupyterLite!") height = self.options.pop("height", None) example_class = self.options.pop("example_class", "") warning_text = self.options.pop("warning_text", None) @@ -604,7 +610,7 @@ def jupyterlite_build(app: Sphinx, error): if completed_process.returncode != 0: if app.env.config.jupyterlite_silence: print( - "`jupyterlite build` failed but it's output has been silenced." + "`jupyterlite build` failed but its output has been silenced." " stdout and stderr are reproduced below.\n" ) print("stdout:", completed_process.stdout.decode()) From 244de38eed13b44f5e05a7648f9d7e51d47d2d56 Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Fri, 29 Mar 2024 17:29:16 +0530 Subject: [PATCH 02/12] State default `:button_text` value if not provided --- docs/directives/try_examples.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/directives/try_examples.md b/docs/directives/try_examples.md index e6aac30..b23142c 100644 --- a/docs/directives/try_examples.md +++ b/docs/directives/try_examples.md @@ -19,7 +19,7 @@ Examples .. try_examples:: Doctest examples sections are parsed and converted to notebooks. Blocks of text - like this become markdown cells. Codeblocks begin with ``>>>``. Contiguous blocks + like this become Markdown cells. Code blocks begin with ``>>>``. Contiguous blocks of code are combined into a single code cell. >>> x = 2 @@ -116,9 +116,10 @@ positioning of the button. The css for the example above is ``` -The `try_examples` directive has options +The `try_examples` directive has these options: + * `:height:` To set a specific value for the height of the [iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) containing the embeddednotebook. -* `:button_text` To customize the text of the button that replaces the rendered examples with an embedded notebook. +* `:button_text` To customize the text of the button that replaces the rendered examples with an embedded notebook. The default value is `"Try it with JupyterLite!"`, or the value of the global configuration variable `try_examples_global_button_text` if it is set in `conf.py`. * `:theme:` This works the same as for the other JupyterLite-Sphinx directives. * `:example_class:` An html class to attach to the outer container for the rendered examples content and embedded notebook. This can be used in a custom css file to allow From 0015c81cf47ba7b79ed37ba1c28a0d6ac853e4d3 Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Fri, 29 Mar 2024 19:43:06 +0530 Subject: [PATCH 03/12] Use global values for `example_class`, `warning` --- jupyterlite_sphinx/jupyterlite_sphinx.py | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/jupyterlite_sphinx/jupyterlite_sphinx.py b/jupyterlite_sphinx/jupyterlite_sphinx.py index df146a9..3c523ae 100644 --- a/jupyterlite_sphinx/jupyterlite_sphinx.py +++ b/jupyterlite_sphinx/jupyterlite_sphinx.py @@ -382,14 +382,31 @@ def run(self): # Use button_text from try_examples_global_button_text if not provided if self.env.config.try_examples_global_button_text is not None: - button_text = self.options.pop( + button_text = self.options.get( "button_text", self.env.config.try_examples_global_button_text ) else: button_text = self.options.pop("button_text", "Try it with JupyterLite!") + + # Use warning_text from try_examples_global_warning_text if not provided + if self.env.config.try_examples_global_warning_text is not None: + warning_text = self.options.get( + "warning_text", self.env.config.try_examples_global_warning_text + ) + else: + warning_text = self.options.pop("warning_text", None) + + # Keep height as is because it is specific to the example being embedded + # into the notebook height = self.options.pop("height", None) - example_class = self.options.pop("example_class", "") - warning_text = self.options.pop("warning_text", None) + + # Use example_class from try_examples_global_theme if not provided + if self.env.config.try_examples_global_theme is not None: + example_class = self.options.get( + "example_class", self.env.config.try_examples_global_theme + ) + else: + example_class = self.options.pop("example_class", "") # We need to get the relative path back to the documentation root from # whichever file the docstring content is in. From 40d4a724a3da1116a7441e90ed9c998503f78b21 Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Fri, 29 Mar 2024 19:48:52 +0530 Subject: [PATCH 04/12] Update options docs for `TryExamples` directive --- docs/directives/try_examples.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/directives/try_examples.md b/docs/directives/try_examples.md index b23142c..4dbae6e 100644 --- a/docs/directives/try_examples.md +++ b/docs/directives/try_examples.md @@ -118,13 +118,14 @@ positioning of the button. The css for the example above is The `try_examples` directive has these options: -* `:height:` To set a specific value for the height of the [iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) containing the embeddednotebook. +* `:height:` To set a specific value for the height of the [iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) containing the embedded notebook. * `:button_text` To customize the text of the button that replaces the rendered examples with an embedded notebook. The default value is `"Try it with JupyterLite!"`, or the value of the global configuration variable `try_examples_global_button_text` if it is set in `conf.py`. * `:theme:` This works the same as for the other JupyterLite-Sphinx directives. * `:example_class:` An html class to attach to the outer container for the rendered examples content and embedded notebook. This can be used in a custom css file to allow for more precise customization, eg. different button styles across different examples. -* `:warning_text:` Prepend a markdown cell to the notebook containing this text, styled to make it clear this is intended as a warning. +The default value is the value of the global configuration variable `try_examples_global_theme`, if it is set in `conf.py`. +* `:warning_text:` Prepend a markdown cell to the notebook containing this text, styled to make it clear this is intended as a warning. The default value is the value of the global configuration variable `try_examples_global_warning_text` if it is set in `conf.py`, otherwise no warning text is added. Here's an example with some options set From 47621ff2dc743ca4491046bc97b9c04009e1291e Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Sat, 30 Mar 2024 15:43:40 +0530 Subject: [PATCH 05/12] Better control flow logic to retrieve configuration Co-Authored-By: Albert Steppi <1953382+steppi@users.noreply.github.com> --- jupyterlite_sphinx/jupyterlite_sphinx.py | 30 ++++++++++-------------- 1 file changed, 12 insertions(+), 18 deletions(-) diff --git a/jupyterlite_sphinx/jupyterlite_sphinx.py b/jupyterlite_sphinx/jupyterlite_sphinx.py index f27ee20..a26d9cb 100644 --- a/jupyterlite_sphinx/jupyterlite_sphinx.py +++ b/jupyterlite_sphinx/jupyterlite_sphinx.py @@ -388,32 +388,26 @@ def run(self): ) # Use button_text from try_examples_global_button_text if not provided - if self.env.config.try_examples_global_button_text is not None: - button_text = self.options.get( - "button_text", self.env.config.try_examples_global_button_text - ) - else: - button_text = self.options.pop("button_text", "Try it with JupyterLite!") + default_button_text = self.env.config.try_examples_global_button_text + if default_button_text is None: + default_button_text = "Try it with JupyterLite!" + button_text = self.options.pop("button_text", default_button_text) # Use warning_text from try_examples_global_warning_text if not provided - if self.env.config.try_examples_global_warning_text is not None: - warning_text = self.options.get( - "warning_text", self.env.config.try_examples_global_warning_text - ) - else: - warning_text = self.options.pop("warning_text", None) + default_warning_text = self.env.config.try_examples_global_warning_text + if default_warning_text is None: + default_warning_text = "Interactive examples are experimental and may not always work as expected." + warning_text = self.options.pop("warning_text", default_warning_text) # Keep height as is because it is specific to the example being embedded # into the notebook height = self.options.pop("height", None) # Use example_class from try_examples_global_theme if not provided - if self.env.config.try_examples_global_theme is not None: - example_class = self.options.get( - "example_class", self.env.config.try_examples_global_theme - ) - else: - example_class = self.options.pop("example_class", "") + default_example_class = self.env.config.try_examples_global_theme + if default_example_class is None: + default_example_class = "" + example_class = self.options.pop("example_class", default_example_class) # We need to get the relative path back to the documentation root from # whichever file the docstring content is in. From 958b12e3697f747b54abaaf2b09990a8bf84ea4f Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Sat, 30 Mar 2024 20:24:19 +0530 Subject: [PATCH 06/12] Simplify `:warning_text` option retrieval logic Do not include a warning text by default, but if a value exists in conf.py, use it. If a directive has its own warning text, then override the global value. Co-Authored-By: Albert Steppi <1953382+steppi@users.noreply.github.com> --- jupyterlite_sphinx/jupyterlite_sphinx.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/jupyterlite_sphinx/jupyterlite_sphinx.py b/jupyterlite_sphinx/jupyterlite_sphinx.py index a26d9cb..fc5a53b 100644 --- a/jupyterlite_sphinx/jupyterlite_sphinx.py +++ b/jupyterlite_sphinx/jupyterlite_sphinx.py @@ -393,10 +393,9 @@ def run(self): default_button_text = "Try it with JupyterLite!" button_text = self.options.pop("button_text", default_button_text) - # Use warning_text from try_examples_global_warning_text if not provided + # Use warning_text from try_examples_global_warning_text by default. If + # it is not provided, don't show any warning text default_warning_text = self.env.config.try_examples_global_warning_text - if default_warning_text is None: - default_warning_text = "Interactive examples are experimental and may not always work as expected." warning_text = self.options.pop("warning_text", default_warning_text) # Keep height as is because it is specific to the example being embedded From 7dad6e20120067617c2213eaa34515943038e096 Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Sat, 30 Mar 2024 20:31:11 +0530 Subject: [PATCH 07/12] Document how propagation for global confvals works Revert "Update options docs for `TryExamples` directive" This reverts commit 40d4a724a3da1116a7441e90ed9c998503f78b21. Revert "State default `:button_text` value if not provided" This reverts commit 244de38eed13b44f5e05a7648f9d7e51d47d2d56. --- docs/directives/try_examples.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/directives/try_examples.md b/docs/directives/try_examples.md index 4dbae6e..75efd9d 100644 --- a/docs/directives/try_examples.md +++ b/docs/directives/try_examples.md @@ -19,7 +19,7 @@ Examples .. try_examples:: Doctest examples sections are parsed and converted to notebooks. Blocks of text - like this become Markdown cells. Code blocks begin with ``>>>``. Contiguous blocks + like this become markdown cells. Codeblocks begin with ``>>>``. Contiguous blocks of code are combined into a single code cell. >>> x = 2 @@ -116,16 +116,14 @@ positioning of the button. The css for the example above is ``` -The `try_examples` directive has these options: - -* `:height:` To set a specific value for the height of the [iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) containing the embedded notebook. -* `:button_text` To customize the text of the button that replaces the rendered examples with an embedded notebook. The default value is `"Try it with JupyterLite!"`, or the value of the global configuration variable `try_examples_global_button_text` if it is set in `conf.py`. +The `try_examples` directive has options +* `:height:` To set a specific value for the height of the [iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) containing the embeddednotebook. +* `:button_text` To customize the text of the button that replaces the rendered examples with an embedded notebook. * `:theme:` This works the same as for the other JupyterLite-Sphinx directives. * `:example_class:` An html class to attach to the outer container for the rendered examples content and embedded notebook. This can be used in a custom css file to allow for more precise customization, eg. different button styles across different examples. -The default value is the value of the global configuration variable `try_examples_global_theme`, if it is set in `conf.py`. -* `:warning_text:` Prepend a markdown cell to the notebook containing this text, styled to make it clear this is intended as a warning. The default value is the value of the global configuration variable `try_examples_global_warning_text` if it is set in `conf.py`, otherwise no warning text is added. +* `:warning_text:` Prepend a markdown cell to the notebook containing this text, styled to make it clear this is intended as a warning. Here's an example with some options set @@ -206,7 +204,10 @@ allowing for specification of examples sections which should not be made interac The button text, theme, and warning text can be set globally with the config variables -`try_examples_global_button_text`, `try_examples_global_theme`, and `try_examples_global_warning_text`. +`try_examples_global_button_text`, `try_examples_global_theme`, and `try_examples_global_warning_text` in `conf.py`; +and these apply both to automatically inserted directives and to manually inserted ones. The +priority of these global settings is lower than that of the specific options set for a manually +inserted directive, which will override the global settings on a per-directive basis. ```python global_enable_try_examples = True @@ -215,7 +216,7 @@ try_examples_global_height = "200px" try_examples_global_warning_text = "Interactive examples are experimental and may not always work as expected." ``` -There is no option to set a global specific height because the proper height +However, there is no option to set a global specific height because the proper height should depend on the size of the examples content. Again, the default height of the embedded notebook's iframe container matches the height of the associated rendered doctest example so that it takes up the same amount of space on the From 998cd260a78a8b337682116d8a87404b0f19cd0a Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Sat, 30 Mar 2024 21:39:17 +0530 Subject: [PATCH 08/12] Revert "However" adverb from global config docs --- docs/directives/try_examples.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/directives/try_examples.md b/docs/directives/try_examples.md index 75efd9d..de2ae99 100644 --- a/docs/directives/try_examples.md +++ b/docs/directives/try_examples.md @@ -216,7 +216,7 @@ try_examples_global_height = "200px" try_examples_global_warning_text = "Interactive examples are experimental and may not always work as expected." ``` -However, there is no option to set a global specific height because the proper height +There is no option to set a global specific height because the proper height should depend on the size of the examples content. Again, the default height of the embedded notebook's iframe container matches the height of the associated rendered doctest example so that it takes up the same amount of space on the From 62b3dea0b88a27e4802c11f388e8be6e77eaeab4 Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Sat, 30 Mar 2024 21:43:17 +0530 Subject: [PATCH 09/12] Move comments, signify clearer global retrieval --- jupyterlite_sphinx/jupyterlite_sphinx.py | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/jupyterlite_sphinx/jupyterlite_sphinx.py b/jupyterlite_sphinx/jupyterlite_sphinx.py index fc5a53b..edd9206 100644 --- a/jupyterlite_sphinx/jupyterlite_sphinx.py +++ b/jupyterlite_sphinx/jupyterlite_sphinx.py @@ -387,27 +387,27 @@ def run(self): directive_key ) - # Use button_text from try_examples_global_button_text if not provided + # Use global configuration values from conf.py in manually inserted directives + # if they are provided and the user has not specified a config value in the + # directive itself. + default_button_text = self.env.config.try_examples_global_button_text if default_button_text is None: default_button_text = "Try it with JupyterLite!" button_text = self.options.pop("button_text", default_button_text) - # Use warning_text from try_examples_global_warning_text by default. If - # it is not provided, don't show any warning text default_warning_text = self.env.config.try_examples_global_warning_text warning_text = self.options.pop("warning_text", default_warning_text) - # Keep height as is because it is specific to the example being embedded - # into the notebook - height = self.options.pop("height", None) - - # Use example_class from try_examples_global_theme if not provided default_example_class = self.env.config.try_examples_global_theme if default_example_class is None: default_example_class = "" example_class = self.options.pop("example_class", default_example_class) + # No global option for height is available, so we use the one provided + # manually in the directive. + height = self.options.pop("height", None) + # We need to get the relative path back to the documentation root from # whichever file the docstring content is in. docname = self.env.docname From f5d9e67dd50ca92c6a9f73f40adbc873e414afd0 Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Sat, 30 Mar 2024 21:43:35 +0530 Subject: [PATCH 10/12] Fix a typo in the directive options --- docs/directives/try_examples.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/directives/try_examples.md b/docs/directives/try_examples.md index de2ae99..56fdf95 100644 --- a/docs/directives/try_examples.md +++ b/docs/directives/try_examples.md @@ -117,7 +117,7 @@ positioning of the button. The css for the example above is The `try_examples` directive has options -* `:height:` To set a specific value for the height of the [iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) containing the embeddednotebook. +* `:height:` To set a specific value for the height of the [iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) containing the embedded notebook. * `:button_text` To customize the text of the button that replaces the rendered examples with an embedded notebook. * `:theme:` This works the same as for the other JupyterLite-Sphinx directives. * `:example_class:` An html class to attach to the outer container for the rendered From f9a36f41cc7c4273d307c863cef0d0acd5ca6a8f Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Sat, 30 Mar 2024 22:54:55 +0530 Subject: [PATCH 11/12] Clarify language for global configuration docs Co-authored-by: Albert Steppi --- docs/directives/try_examples.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/directives/try_examples.md b/docs/directives/try_examples.md index 56fdf95..12c0d1c 100644 --- a/docs/directives/try_examples.md +++ b/docs/directives/try_examples.md @@ -205,9 +205,8 @@ allowing for specification of examples sections which should not be made interac The button text, theme, and warning text can be set globally with the config variables `try_examples_global_button_text`, `try_examples_global_theme`, and `try_examples_global_warning_text` in `conf.py`; -and these apply both to automatically inserted directives and to manually inserted ones. The -priority of these global settings is lower than that of the specific options set for a manually -inserted directive, which will override the global settings on a per-directive basis. +these apply both to automatically and manually inserted directives. Options set explicitly in a directive will +override the global configuration. ```python global_enable_try_examples = True From cd542e3c48ba2935881f13a8079f56e6c84a8009 Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Sat, 30 Mar 2024 22:57:00 +0530 Subject: [PATCH 12/12] Reword comment about setting global height --- jupyterlite_sphinx/jupyterlite_sphinx.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/jupyterlite_sphinx/jupyterlite_sphinx.py b/jupyterlite_sphinx/jupyterlite_sphinx.py index edd9206..f9817b0 100644 --- a/jupyterlite_sphinx/jupyterlite_sphinx.py +++ b/jupyterlite_sphinx/jupyterlite_sphinx.py @@ -404,8 +404,7 @@ def run(self): default_example_class = "" example_class = self.options.pop("example_class", default_example_class) - # No global option for height is available, so we use the one provided - # manually in the directive. + # A global height cannot be set in conf.py height = self.options.pop("height", None) # We need to get the relative path back to the documentation root from