From 1ad07d26d571fa648d53c72efc8fe7bc18f425cc Mon Sep 17 00:00:00 2001
From: Bryan Weber <bryan.w.weber@gmail.com>
Date: Sun, 7 Jul 2024 22:05:32 -0400
Subject: [PATCH] Update glue docs to mention NumPy 2.0 changes

Changes to the text/plain representation of NumPy objects for NumPy >= 2.0 mean that we need a workaround for formatting.
---
 docs/render/glue.md | 27 ++++++++++++++++++++++++---
 1 file changed, 24 insertions(+), 3 deletions(-)

diff --git a/docs/render/glue.md b/docs/render/glue.md
index 66caeeb6..6b2cdcf9 100644
--- a/docs/render/glue.md
+++ b/docs/render/glue.md
@@ -25,7 +25,7 @@ To glue keys from other notebooks, see {ref}`glue/crossdoc`.
 ## Save variables in code cells
 
 You can use `myst_nb.glue()` to assign the output of a variable to a key of your choice.
-`glue` will store all of the information that is normally used to display that variable (ie, whatever happens when you display the variable by putting it at the end of a cell).
+`glue` will store all of the information that is normally used to display that variable (that is, whatever happens when you display the variable by putting it at the end of a cell).
 Choose a key that you will remember, as you will use it later.
 
 The following code glues a variable inside the notebook:
@@ -137,12 +137,12 @@ These variables can be pasted using one of the roles or directives in the `glue:
 
 ### The `glue` role/directive
 
-The simplest role and directive are `glue` (a.k.a. `glue:any`),
+The simplest role and directive are `glue` (also known as `glue:any`),
 which paste the glued output inline or as a block respectively,
 with no additional formatting.
 Simply add:
 
-````
+````md
 ```{glue} your-key
 ```
 ````
@@ -219,6 +219,27 @@ For example, the following: ``My rounded mean: {glue:text}`boot_mean:.2f` `` wil
 
 My rounded mean: {glue:text}`boot_mean:.2f` (95% CI: {glue:text}`boot_clo:.2f`/{glue:text}`boot_chi:.2f`).
 
+````{warning}
+As of NumPy 2.0, the `text/plain` representation of [NumPy objects has changed](https://numpy.org/devdocs/release/2.0.0-notes.html#representation-of-numpy-scalars-changed).
+Using text formatting with NumPy>=2.0 will give warnings like:
+
+```
+sphinx.errors.SphinxWarning: <filename>:257:Failed to format text/plain data: could not convert string to float: 'np.float64(0.9643970836113095)' [mystnb.glue]
+```
+
+This can be resolved by either formatting the number before glueing or by setting NumPy to use legacy print options, as shown below.
+
+```python
+var = np.float(1.0)
+# Format the variable before glueing
+glue("var_glue", f"{var:.2f}")
+
+# Or set NumPy legacy print options
+np.setprintoptions(legacy="1.25")
+glue("var_glue", var)
+```
+````
+
 +++
 
 ### The `glue:figure` directive