Glue System

def glue(name: str, variable, display: bool = True) -> None:
    """
    Glue a variable into the notebook's cell metadata.
    
    Parameters:
    - name: str - Unique name for the variable for later reference
    - variable: Any - Python object whose display value should be stored
    - display: bool - Whether to display the object when gluing (default True)
    
    The stored information is what is displayed when you print or show 
    the object in a Jupyter Notebook, not the object itself.
    """

def load_glue_sphinx(app: Sphinx) -> None:
    """
    Load glue functionality for Sphinx applications.
    
    Parameters:
    - app: Sphinx application instance
    
    Registers glue roles, directives, and domain with Sphinx.
    """

def load_glue_docutils(app: DocutilsApp) -> None:
    """
    Load glue functionality for docutils applications.
    
    Parameters:
    - app: DocutilsApp container for roles and directives
    
    Registers glue roles and directives with docutils.
    """

class GlueRole:
    """
    Inline role to insert glued variable content.
    
    Usage: :glue:`variable_name`
    """

class GlueDirective:
    """
    Block directive to insert glued variable content.
    
    Usage:
    ```{glue} variable_name
    ```
    """

class GlueFigureDirective:
    """
    Figure directive for glued content with caption support.
    
    Usage:
    ```{glue:figure} variable_name
    :name: "figure-name"
    :align: center
    
    Figure caption text
    ```
    """

class GlueDomain:
    """
    Sphinx domain for glue functionality.
    
    Manages glue variable storage, cross-referencing, and 
    integration with Sphinx's reference system.
    """

from myst_nb import glue
import numpy as np
import matplotlib.pyplot as plt

# Glue a simple value
result = 42 * 1.5
glue("calculation_result", result)

# Glue an array
data = np.array([1, 2, 3, 4, 5])
glue("my_array", data)

# Glue a plot
fig, ax = plt.subplots()
ax.plot([1, 2, 3, 4], [1, 4, 2, 3])
ax.set_title("Sample Plot")
glue("sample_plot", fig, display=False)

The calculation result is {glue:}`calculation_result`.

Our array contains {glue:}`my_array`.

Here is our data:

```{glue} my_array

### Figure References

```markdown
```{glue:figure} sample_plot
:name: "fig-sample"
:align: center

This is our sample plot showing the trend.

### Advanced Gluing with DataFrames

```python
import pandas as pd
from myst_nb import glue

# Create and glue a DataFrame
df = pd.DataFrame({
    'A': [1, 2, 3],
    'B': [4, 5, 6],
    'C': [7, 8, 9]
})
glue("results_table", df)

# Glue summary statistics
glue("mean_A", df['A'].mean())
glue("max_B", df['B'].max())

## Results

```{glue:figure} results_table
:name: "table-results"

Summary of results

### Conditional Display

```python
from myst_nb import glue

# Glue without immediate display for later use only
sensitive_data = compute_sensitive_results()
glue("internal_calc", sensitive_data, display=False)

# Display-friendly version
public_summary = create_summary(sensitive_data)
glue("public_results", public_summary, display=True)

glue("shared_constant", 3.14159)

Using the constant {glue:}`shared_constant` from the previous analysis...