TryExamples directive#

jupyterlite-sphinx provides the experimentaltry_examples directive which allowsdocstring examples sections written indoctest format to be swapped with an embedded classic Notebook at the push of a button.

Below is an example of the directive in use. The button has been styled with customcss as explained in the configuration section below. Without custom css, the button willbe plain and unadorned.

Note that as starting JupyterLite can download a significant amount of data, andthat the Jupyter interface is not optimized for mobile, the buttons will behidden on mobile by default (screen width 480px or smaller). This can bechanged by overwriting with custom CSS.

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    of code are combined into a single code cell.    >>> x = 2    >>> y = 2    >>> x + y    4``...`` is used to continue multiline statements.    >>> def f(x, y):    ...     return x + y    >>> f(2, 2)    4    Inline LaTeX like :math:`x + y = 4` is converted, as is block LaTeX like    .. math::        \int_{x=-\infty}^{\infty}e^{-x^2}\mathrm{d}x = \sqrt{\pi}    If you are displaying `math output <https://www.sphinx-doc.org/en/master/usage/extensions/math.html>`_    with sphinx. Sphinx links such as the one in the previous sentence are also converted to    markdown format.

and here is how this looks and works when rendered.

Examples#

Doctest examples sections are parsed and converted to notebooks. Blocks of textlike this become markdown cells. Codeblocks begin with>>>. Contiguous blocksof code are combined into a single code cell.

>>>x=2>>>y=2>>>x+y4

… is used to continue multiline statements.

>>>deff(x,y):...returnx+y>>>f(2,2)4

Inline LaTeX like\(x + y = 4\) is converted, as is block LaTeX like

\[\int_{-\infty}^{\infty}e^{-x^2}\mathrm{d}x = \sqrt{\pi}\]

If you are displayingmath outputwith sphinx. Sphinx links such as the one in the previous sentence are also converted tomarkdown format.

By default, the height of the embedded notebook’s iframe container is calculated to match the height of the rendered doctest examples so that it takes up the same amount of space on thepage.

Configuration#

The position and style of the button can be customized to match your documentation’sdesign by adding custom css as explained in Sphinx’s documentationhere. The buttons have classtry_examples_button. The buttons are placed withincontainers with classtry_examples_button_container, which can be selected to adjust thepositioning of the button. The css for the example above is

.try_examples_button{color:white;background-color:#0054a6;border:none;padding:5px10px;border-radius:10px;margin-bottom:5px;box-shadow:02px5pxrgba(108,108,108,0.2);}.try_examples_button:hover{background-color:#0066cc;transform:scale(1.02);box-shadow:02px5pxrgba(0,0,0,0.2);cursor:pointer;}.try_examples_button_container{display:flex;justify-content:flex-end;}

Thetry_examples directive has options

  • :height: To set a specific value for the height of theiframe 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 renderedexamples content and embedded notebook. This can be used in a custom css file to allowfor 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.

Here’s an example with some options set

..try_examples:::button_text: Try it in your browser!:height: 400px:example_class: blue-bottom:warning_text: Interactive examples are experimental and may not always work as expected.    The button text has changed and the height now exceeds the size of the content.    >>> x = 2    >>> y = 2    >>> x + y    4    We've also added the``blue-bottom`` class, the button should appear as blue,    below the examples, and on the left side of the screen.    See`try_examples.css<https://github.com/jupyterlite/jupyterlite-sphinx/blob/main/docs/_static/try_examples.css>`_    to see how we achieved this via custom css.

and here is the result

The button text has changed and the height now exceeds the size of the content.

>>>x=2>>>y=2>>>x+y4

We’ve also added theblue-bottom class, the button should appear as blue,below the examples, and on the left side of the screen.

Seetry_examples.cssto see how we achieved this via custom css.

Global Configuration#

For projects with a large number of existing doctest examples, it would be tedious to addthetry_examples directive manually to each docstring example. If you are usingsphinx.ext.autodoc with eithernumpydoc orsphinx.ext.napoleon, youcan set the option.

global_enable_try_examples=True

in your sphinxconf.py in order to automatically insert thetry_examples directivein examples sections during the"autodoc-process-docstring" event. This works byidentifying section headings. An examples section includes all of the content beneathan examples heading, and up to either the next heading or the end of the docstring ifthere are no further headings. One ofnumpydoc orsphinx.ext.napoleon is requiredbecause these map the section headers to a standardized format.

If an examples section already contains atry_examples directive, no additionaldirectives will be inserted, allowing for specific cases to be separately configuredif needed. Adding the comment

.. disable_try_examples

as the first non-empty line underthe section header for an examples section will prevent a directive from being inserted,allowing for specification of examples sections which should not be made interactive.

The button text, theme, and warning text can be set globally with the config variablestry_examples_global_button_text,try_examples_global_theme, andtry_examples_global_warning_text inconf.py;these apply both to automatically and manually inserted directives. Options set explicitly in a directive willoverride the global configuration.

global_enable_try_examples=Truetry_examples_global_button_text="Try it in your browser!"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 heightshould depend on the size of the examples content. Again, the default height ofthe embedded notebook’s iframe container matches the height of the associatedrendered doctest example so that it takes up the same amount of space on thepage. For very small examples this may lead to an unusably small notebook. It’s possibleto set a global minimum height in thetry_examples.json configuration file describedbelow.

try_examples.json configuration file.#

Users may place a configuration filetry_examples.json in the source root oftheir documentation. This configuration file will be copied to the build root ofthe deployed documentation. Changes to the configuration file in the build rootwill be respected without rebuilding the documentation, allowing for runtimeconfiguration.

The current options are

“ignore_patterns”#

The format is a list ofJavaScript Regex patterns attached to the key"ignore_patterns" like below.

{"ignore_patterns":["^\/latest/.*","^\/stable\/reference\/generated\/example.html"]}

TryExamples buttons will be hidden in url pathnames matching at least one of thesepatterns, effectively disabling the interactive documentation. In the provided example:

  • The pattern"^\/latest\/.*" disables interactive examples for urls for the documentationfor the latest version of the package, which may be useful if this documentation isfor a development version for which a corresponding package build is not availablein a JupyterLite kernel.

  • The pattern"^\/stable\/reference\/generated\/example.html" targets a particular urlin the documentation for the latest stable release.

Note that these patterns should match thepathname of the url, not the full url. This is the path portion ofthe url. For instance, the pathname of https://jupyterlite-sphinx.readthedocs.io/en/latest/directives/try_examples.html is/en/latest/directives/try_examples.html. Also, note that since these are JavaScript-based regularexpressions, to use special characters in the regular expression (such as/), theymust be escaped with a backslash (\).

Again, the configuration file can be added or edited within the deployed documentation,allowing for disabling or enabling examples without rebuilding the documentation.

“global_min_height”#

To avoid having unusably small notebooks for very small examples due to the default ofhaving the embedded notebooks’ iframe containers take the same amount of space as therendered content they replace, users can set a global minimum height intry_examples.json.

{"global_min_height":"400px"}

This allows the minimum height to be set or changed without rebuilding the docs. Thisconfiguration value will be ignored when a specific height is supplied as an option to..try_examples::.

Other considerations#

If you are using theTryExamples directive in your documentation, you’ll need to ensurethat the version of the package installed in the Jupyterlite kernel you are usingmatches that of the version you are documenting.