try_examples_global_button_text does not propagate to custom .. try_examples:: directives

[agriyakhetarpal]

Description

When using the try_examples_global_button_text configuration value to customise the text displayed on every button, the text is used on buttons for docstring-based examples present in the API documentation for a library. However, buttons that are manually created/enabled using the .. try_examples:: directive on code snippets outside of docstrings (such as those written in-line in .rst files, rather than .py files) do not respect this configuration and use the placeholder text "Try it with Jupyterliteinstead of thetry_examples_global_button_textvalue set inconf.py`.

It is to be noted that a :button_text option is available in order to customise the text for the granularity of a specific button, but doing this for documentation websites where such buttons might be several in number might not make sense.

Reproduce

In a standard documentation deployment provided with Sphinx, please follow these steps to reproduce:

1. Add try_examples_global_button_text = "Your text here" to conf.py
2. Add any code snippet to a .rst file tracked by Sphinx for inclusion in the built docs, like this:

The NumPy library provides several functions and tooling for array computing.
For example, you may try ``numpy.eye`` to represent an array that looks like an identity matrix:

.. try_examples::

  >>> import numpy as np
  >>> np.eye(2)
  array([[1, 0],
       [0, 1]])

3. Build the documentation, either locally, or in CI, or through any other methods.

A simple reproducer is available on a PR preview on Read the Docs for the PyWavelets documentation, as follows:

The example mentioned in the pywt.families() docstring has the button with the "Try it in your browser" text, as intended:

However, on the same page, code snippets coming from wavelets.rst, i.e., those not from .. autofunction:: directives:

don't have the correct text as mentioned above.

Here is a link to the specified page: https://pywavelets--728.org.readthedocs.build/en/728/ref/wavelets.html

xref: PyWavelets/pywt#728

Expected behavior

The expected behaviour here, IMO, is that .. try_examples::, in the absence of an :button_text: option, should use the value added to try_examples_global_button_text instead of the "Try it with Jupyterlite" boilerplate/placeholder text (it is a global value, after all, as noted in its name!)

Therefore, a summary is as follows:

1. If try_examples_global_button_text is not None, apply it for all examples and .. try_examples:: directives
2. If a .. try_examples:: directive placed somewhere has a custom :button_text:, use that instead, overriding try_examples_global_button_text

Context

• JupyterLite version: jupyterlite-core (0.2.3), jupyterlite-sphinx (0.12.0)
• Operating System and version: macOS Sonoma v14.3
• Browser and version: Brave Browser, version 1.64.109 with Chromium: 123.0.6312.58 (Official Build) (arm64)

[steppi]

I'm not sure this should be classified as a bug. I think it can be separated into a documentation issue, that it's not well documented that try_examples_global_x only applies to automatically inserted instances of the directive, and a request for an enhancement to have global_enable_try_examples find all instances of the directive that are already there and insert the global config options when config options are not supplied directly.

[agriyakhetarpal]

I agree. It's not completely a bug, but as a feature it would be really useful! I'm happy to write a PR to do both things: update the documentation about this, and also let .. try_examples:: percolate these global config options (I would appreciate some pointers on the latter!)