### Complete conf.py Example for nbsphinx

Source: https://context7.com/spatialaudio/nbsphinx/llms.txt

This Python code snippet demonstrates a comprehensive configuration file for nbsphinx, a Sphinx extension for integrating Jupyter Notebooks. It covers essential settings such as required extensions, project information, notebook execution parameters, prompt customization, thumbnail generation, and intersphinx mappings. This example provides a robust starting point for setting up nbsphinx in a Sphinx project.

```python
# conf.py
import os

# Required extension
extensions = [
    'nbsphinx',
    'sphinx.ext.mathjax',
    'sphinx.ext.intersphinx',
]

# Project information
project = 'My Project'
author = 'Author Name'
copyright = '2024, Author Name'

# Notebook execution settings
bsphinx_execute = 'auto'
bsphinx_timeout = 120
bsphinx_allow_errors = False
bsphinx_kernel_name = 'python3'

# Figure format configuration
bsphinx_execute_arguments = [
    "--InlineBackend.figure_formats={'svg', 'pdf'}",
]

# Prompt customization
bsphinx_input_prompt = 'In [%s]:'
bsphinx_output_prompt = 'Out[%s]:'

# Gallery thumbnails
bsphinx_thumbnails = {
    'examples/*': '_static/default-thumb.png',
}

# Prolog added before each notebook
bsphinx_prolog = r""
{% set docname = env.doc2path(env.docname, base=False)|string %}

.. note::
   This page was generated from ``{{ docname }}``.
"

# MathJax configuration
mathjax3_config = {
    'tex': {'tags': 'ams', 'useLabelIds': True},
}

# Exclude patterns
exclude_patterns = ['_build', '**.ipynb_checkpoints', 'Thumbs.db']

# HTML output options
html_theme = 'sphinx_rtd_theme'
html_sourcelink_suffix = ''

# LaTeX output options
latex_elements = {
    'papersize': 'a4paper',
}

# Intersphinx mapping
intersphinx_mapping = {
    'python': ('https://docs.python.org/3/', None),
    'numpy': ('https://numpy.org/doc/stable/', None),
}
```

--------------------------------

### Run Sphinx Quickstart

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/usage.ipynb

Command to initialize a new Sphinx project. It prompts the user for configuration details and sets up the basic directory structure and files.

```bash
python3 -m sphinx.cmd.quickstart
```

--------------------------------

### Install sphinx-autobuild

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/usage.ipynb

Command to install the sphinx-autobuild package, which provides live reloading for Sphinx documentation builds.

```bash
python3 -m pip install sphinx-autobuild
```

--------------------------------

### Run sphinx-autobuild for Live HTML

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/usage.ipynb

Command to start sphinx-autobuild, which automatically rebuilds HTML documentation and refreshes the browser upon detecting file changes. Serves the documentation at http://localhost:8000/.

```bash
python3 -m sphinx_autobuild <source-dir> <build-dir>
```

--------------------------------

### Create Plot for Documentation

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/gallery/thumbnail-from-conf-py.ipynb

An example of generating a standard plot for display in the notebook documentation, distinct from the thumbnail generation process.

```python
fig, ax = plt.subplots(figsize=[6, 3])
ax.plot([4, 9, 7, 20, 6, 33, 13, 23, 16, 62, 8], 'r:');
```

--------------------------------

### Python Code Block Example

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/markdown-cells.ipynb

A simple example of a Python code block with syntax highlighting.

```python
print("Hello, world!")
```

--------------------------------

### Example Notebook Code Cell

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/custom-css.ipynb

A simple Python code cell example within a notebook, demonstrating a calculation.

```python
6 * 7
```

--------------------------------

### Generate Example Data for Plotting

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/gallery/cell-metadata.ipynb

Creates a 2D dataset 'z' using NumPy based on a mathematical function. This data is intended for visualization purposes, such as creating heatmaps or contour plots.

```python
x, y = np.meshgrid(np.arange(-3, 3, 0.1), np.arange(-2, 2, 0.1))
z = (1 - x / 2 + x ** 5 + y ** 3) * np.exp(-x ** 2 - y ** 2)
```

--------------------------------

### Install nbsphinx using pip

Source: https://context7.com/spatialaudio/nbsphinx/llms.txt

Installs the nbsphinx package using pip. This is the primary method for adding nbsphinx to your Python environment.

```bash
pip install nbsphinx
```

--------------------------------

### Install nbsphinx with Pip

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/installation.ipynb

Installs or upgrades the nbsphinx package using pip, Python's package installer. This command can be used to install the latest release or update an existing installation.

```bash
python3 -m pip install nbsphinx
```

```bash
python3 -m pip install --upgrade nbsphinx
```

--------------------------------

### Python Domain Object Example

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/a-normal-rst-file.rst

An example demonstrating the use of Sphinx's domain objects, specifically a Python function directive (`py:function`), for documenting code elements and enabling cross-referencing within the documentation.

```rst
.. py:function:: example_python_function(foo)

    This is just for testing domain object links.

    :param str foo: Example string parameter

    .. seealso::
```

--------------------------------

### Manage Rare Library Dependencies

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/pre-executed.ipynb

Shows how to include code that relies on libraries that are difficult to install or maintain in the build environment. Pre-executing ensures the result is captured without requiring the library at build time.

```python
from a_very_rare_library import calculate_the_answer
calculate_the_answer()
```

--------------------------------

### Install nbsphinx with Conda

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/installation.ipynb

Installs the nbsphinx package using the conda package manager from the conda-forge channel. This is recommended for users who manage their Python environments with conda.

```bash
conda install -c conda-forge nbsphinx
```

--------------------------------

### Handling Unsupported MIME Types with nbsphinx

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/code-cells.ipynb

This example shows how nbsphinx handles cells that produce output with unsupported MIME types. Instead of failing silently, nbsphinx displays a warning message, providing better visibility into potential issues. The code demonstrates creating a display object with multiple MIME types.

```python
display({
    'text/x-python': 'print("Hello, world!")',
    'text/x-haskell': 'main = putStrLn "Hello, world!"',
}, raw=True)
```

--------------------------------

### Apply CSS to Notebooks via conf.py

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/custom-css.ipynb

This Python configuration uses nbsphinx_prolog with a raw HTML directive to inject CSS styles specifically for Jupyter notebooks. The example styles the H1 tags with chartreuse color.

```python
nbsphinx_prolog = """
.. raw:: html

    <style>
        h1 {
            color: chartreuse;
        }
    </style>
"""
```

--------------------------------

### Set Custom Output Prompt for Nbsphinx

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/configuration.ipynb

Configures the output prompt string for code cells in nbsphinx. The '%s' placeholder is replaced by the execution count. This example demonstrates how to set an output prompt similar to the Classic Notebook.

```python
nbsphinx_output_prompt = 'Out[%s]:'
```

--------------------------------

### Set Custom Input Prompt for Nbsphinx

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/configuration.ipynb

Configures the input prompt string for code cells in nbsphinx. The '%s' placeholder is replaced by the execution count. This example shows how to achieve a prompt similar to the Classic Notebook interface.

```python
nbsphinx_input_prompt = 'In [%s]:'
```

--------------------------------

### Apply CSS to RST Files via conf.py

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/custom-css.ipynb

This Python configuration uses rst_prolog with a raw HTML directive to inject CSS styles specifically for RST files. The example styles the H1 tags with fuchsia color.

```python
rst_prolog = """
.. raw:: html

    <style>
        h1 {
            color: fuchsia;
        }
    </style>
"""
```

--------------------------------

### Configure nbsphinx for Markdown files

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/a-markdown-file.md

This configuration snippet enables the use of Markdown files as Sphinx source files by mapping the .md extension to Jupytext's R Markdown reader. It requires the jupytext package to be installed in the environment.

```python
nbsphinx_custom_formats = {
    '.md': ['jupytext.reads', {'fmt': 'Rmd'}],
}
```

--------------------------------

### Example of Cells Causing Errors in nbsphinx (Python)

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/allow-errors.ipynb

Demonstrates code cells within a Jupyter notebook that are expected to raise exceptions. When 'allow_errors' is enabled in the notebook's metadata or globally, these cells will execute without halting the Sphinx build process. The output shows the results of valid code alongside error indications for invalid code.

```python
nonsense
```

```python
42 / 0
```

```python
6 * 7
```

--------------------------------

### Define Environment Variables for mybinder.org

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/configuring-kernels.ipynb

Configure environment variables for use with mybinder.org by creating a `.binder/start` script. This script should export the desired variables before executing the notebook.

```bash
#!/bin/bash
export MY_DUMMY_VARIABLE="Hello from .binder/start!"
exec "$@"
```

--------------------------------

### Execute Python Code and Display Output

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/code-cells.ipynb

Demonstrates basic code cell execution, standard output, and standard error handling in Jupyter notebooks.

```python
print('Hello, world!')
6 * 7
```

```python
import sys
print("I'll appear on the standard error stream", file=sys.stderr)
print("I'll appear on the standard output stream")
"I'm the 'normal' output"
```

--------------------------------

### Configure Read the Docs for nbsphinx

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/usage.ipynb

Configuration files for Read the Docs to build documentation. Includes the .readthedocs.yml build configuration and a requirements.txt file for dependencies.

```yaml
version: 2
build:
  os: ubuntu-22.04
  tools:
    python: "3"
python:
  install:
    - requirements: doc/requirements.txt
```

```text
ipykernel
nbsphinx
git+https://github.com/spatialaudio/nbsphinx.git@master
```

--------------------------------

### Run Sphinx build commands

Source: https://context7.com/spatialaudio/nbsphinx/llms.txt

Provides various commands to build Sphinx documentation, including generating HTML and LaTeX output, performing parallel builds, checking links, and forcing a full rebuild. These commands are executed from the command line.

```bash
# Build HTML output
python3 -m sphinx . _build/html

# Parallel build with 4 processes
python3 -m sphinx . _build/html -j4

# Build LaTeX/PDF output
python3 -m sphinx . _build/latex -b latex

# Check links in documentation
python3 -m sphinx . _build/linkcheck -b linkcheck

# Force rebuild all files
python3 -m sphinx . _build/html -E
```

--------------------------------

### Build HTML Documentation with Sphinx

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/usage.ipynb

Command to build HTML documentation from source files, including Jupyter notebooks processed by nbsphinx. Supports parallel builds for faster processing.

```bash
python3 -m sphinx <source-dir> <build-dir>
```

```bash
python3 -m sphinx <source-dir> <build-dir> -j<number-of-processes>
```

```bash
python3 -m sphinx . _build -j4
```

--------------------------------

### Configure GitLab CI/CD

Source: https://context7.com/spatialaudio/nbsphinx/llms.txt

Automates the documentation build and deployment process using GitLab CI/CD pipelines.

```yaml
image: python:3-slim
variables:
  PIP: python3 -m pip
  SPHINX: python3 -m sphinx -W --keep-going --color

build-docs:
  stage: build
  script:
    - apt-get update -y
    - apt-get install -y --no-install-recommends pandoc
    - $PIP install -r doc/requirements.txt
    - $SPHINX -d doctrees doc html -b html
  artifacts:
    paths:
      - html
```

--------------------------------

### Create and Display Xarray Dataset

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/code-cells.ipynb

Demonstrates how to construct an Xarray Dataset from DataArrays and display it. The HTML representation is used in notebook environments, while LaTeX/PDF output falls back to plain text.

```python
import xarray as xr
a = {}
for name in ["t", "q"]: 
    da = xr.DataArray(
        [[[11, 12, 13], [21, 22, 23], [31, 32, 33]], [[14, 15, 16], [24, 25, 26], [34, 35, 36]]],
        coords={"level": ["500", "700"], "x": [1, 2, 3], "y": [4, 5, 6]},
        name=name,
        attrs={"param": name}
    )
    a[name] = da
ds = xr.Dataset(a, attrs={"title": "Demo dataset", "year": 2024})
ds
```

--------------------------------

### Configure GitLab CI/CD for Documentation Deployment

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/usage.ipynb

A .gitlab-ci.yml configuration to build and deploy documentation using Sphinx and nbsphinx on GitLab Pages.

```yaml
image: python:3-slim

variables:
  PIP: python3 -m pip
  SPHINX: python3 -m sphinx -W --keep-going --color

build-docs:
  stage: build
  script:
    - apt-get update -y
    - apt-get install -y --no-install-recommends pandoc
    - $PIP install -r doc/requirements.txt
    - $SPHINX -d doctrees doc html -b html
    - $SPHINX -d doctrees doc linkcheck -b linkcheck
  artifacts:
    when: always
    paths:
      - html
      - linkcheck/output.*
    
pages:
  stage: deploy
  variables:
    GIT_STRATEGY: none
  script:
    - mv html public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
```

--------------------------------

### Documenting Exceptions

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/pre-executed.ipynb

Illustrates how to present code that intentionally raises an exception. Pre-executing allows the error trace to be saved and displayed in the documentation.

```python
1 / 0
```

--------------------------------

### Suppress Warnings Configuration in Sphinx

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/configuration.ipynb

Allows silencing specific Sphinx warnings. This is useful when you are aware of a warning and choose to ignore it. The example shows how to suppress all warnings originating from 'nbsphinx' or specific nbsphinx modules.

```python
suppress_warnings = [
    'nbsphinx',
]
```

```python
suppress_warnings = [
    'nbsphinx.localfile',
    'nbsphinx.gallery',
    'nbsphinx.thumbnail',
    'nbsphinx.notebooktitle',
    'nbsphinx.ipywidgets',
]
```

--------------------------------

### Configure nbsphinx Epilog

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/markdown-cells.ipynb

Demonstrates how to set the nbsphinx_epilog configuration variable in the conf.py file.

```python
nbsphinx_epilog = r"""
.. footbibliography::
"""
```

--------------------------------

### Define Thumbnail via nbsphinx-thumbnail Tag

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/gallery/cell-tag.ipynb

This snippet demonstrates the standard matplotlib setup for generating a plot. When this cell is tagged with 'nbsphinx-thumbnail' in the notebook metadata, nbsphinx will use this specific plot as the thumbnail for the document.

```python
import matplotlib.pyplot as plt
fig, ax = plt.subplots(figsize=[6, 3])
ax.plot([4, 9, 7, 20, 6, 33, 13, 23, 16, 62, 8])
```

--------------------------------

### Configure nbsphinx Thumbnails and Galleries

Source: https://context7.com/spatialaudio/nbsphinx/llms.txt

Maps notebooks to thumbnail images and uses the nbgallery directive to generate visual galleries.

```python
nbsphinx_thumbnails = {
    'notebooks/example': 'images/example-thumb.png',
    'gallery/*': 'images/default-gallery-thumb.png',
    'tutorials/*-beginner': 'images/beginner-thumb.png',
    'gallery/featured': 'images/featured-thumb.png',
}
```

```rst
.. nbgallery::
   :caption: Example Gallery
   :name: example-gallery
   :glob:

   gallery/*
```

--------------------------------

### Interactive Widgets and Linking

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/code-cells.ipynb

Demonstrates creating ipywidgets, synchronizing state across multiple views, and linking widget values using kernel-based (link/dlink) or client-side (jslink/jsdlink) methods.

```python
import ipywidgets as w
slider = w.IntSlider()
slider.value = 42
link = w.IntSlider(description='link')
w.link((slider, 'value'), (link, 'value'))
jslink = w.IntSlider(description='jslink')
w.jslink((slider, 'value'), (jslink, 'value'))
dlink = w.IntSlider(description='dlink')
w.dlink((slider, 'value'), (dlink, 'value'))
jsdlink = w.IntSlider(description='jsdlink')
w.jsdlink((slider, 'value'), (jsdlink, 'value'))
w.VBox([link, jslink, dlink, jsdlink])
```

--------------------------------

### Apply CSS to a Single Notebook

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/custom-css.ipynb

This HTML snippet can be placed directly into a Markdown cell within a Jupyter notebook to apply custom CSS styles only to that specific notebook. This example hides the input and output prompts.

```html
<style>
    .nbinput .prompt,
    .nboutput .prompt {
        display: none;
    }
</style>
```

--------------------------------

### Display Rich Media and LaTeX

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/code-cells.ipynb

Shows how to render images, SVG files, and mathematical equations using IPython display utilities.

```python
from IPython.display import Image, SVG, Math, Latex
i = Image(filename='images/notebook_icon.png')
display(i)
SVG(filename='images/python_logo.svg')
eq = Math(r'\int\limits_{-\infty}^\infty f(x) \delta(x - x_0) dx = f(x_0)')
display(eq)
Latex(r'This is a \LaTeX{} equation: $a^2 + b^2 = c^2$')
```

--------------------------------

### Execute Sphinx Build for LaTeX Output

Source: https://github.com/spatialaudio/nbsphinx/blob/master/include-in-latex/README.md

Run the Sphinx build process using a custom configuration directory to override default settings for LaTeX integration.

```bash
python -m sphinx ../doc _build -c . -b latex
```

--------------------------------

### Displaying 24-bit RGB ANSI Colors in Python

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/code-cells.ipynb

This Python code generates a gradient of 24-bit RGB colors using ANSI escape sequences. It defines a start and end RGB color and interpolates between them to create a smooth color transition across the output line.

```python
start = 255, 0, 0
end = 0, 0, 255
length = 79
out = []

for i in range(length):
    rgb = [start[c] + int(i * (end[c] - start[c]) / length) for c in range(3)]
    out.append('\x1b['
               '38;2;{rgb[2]};{rgb[1]};{rgb[0]};'
               '48;2;{rgb[0]};{rgb[1]};{rgb[2]}mX\x1b[m'.format(rgb=rgb))
print(''.join(out))
```

--------------------------------

### Add Content with nbsphinx_prolog and nbsphinx_epilog

Source: https://context7.com/spatialaudio/nbsphinx/llms.txt

Add custom content before (prolog) and after (epilog) each notebook in the generated output. These strings support reStructuredText markup and Jinja2 templating, allowing dynamic content generation.

```python
# conf.py

# Simple static prolog
bsphinx_prolog = """
.. note::
   This page was generated from a Jupyter notebook.

----
"""

# Dynamic prolog with Jinja2 templating
bsphinx_prolog = r"""
{% set docname = env.doc2path(env.docname, base=False)|string %}

.. note::
   Download this notebook: :download:`{{ docname }}`

"""

# Epilog with links
bsphinx_epilog = """
----

Generated by nbsphinx_ from a Jupyter_ notebook.

.. _nbsphinx: https://nbsphinx.readthedocs.io/
.. _Jupyter: https://jupyter.org/
"""
```

--------------------------------

### Include Local Image using Markdown

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/markdown-cells.ipynb

Demonstrates how to include a local image using Markdown syntax. This is a common way to embed images in documentation.

```markdown
![Jupyter notebook icon](images/notebook_icon.png)
```

--------------------------------

### Configure nbsphinx_thumbnails in conf.py

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/gallery/thumbnail-from-conf-py.ipynb

This snippet shows the configuration syntax for mapping notebook paths to specific image files within the Sphinx conf.py file. Note that the notebook path excludes the .ipynb extension.

```python
nbsphinx_thumbnails = {
    'gallery/thumbnail-from-conf-py': 'gallery/a-local-file.png',
}
```

--------------------------------

### Build PDF from LaTeX with latexmk

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/usage.ipynb

Command to use latexmk for automatically building a PDF from LaTeX output. The -pvc flag enables continuous viewing and rebuilding.

```bash
latexmk -pdf -pvc
```

```bash
latexmk -pdf -pvc -f
```

--------------------------------

### Capturing Client-Specific Outputs

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/pre-executed.ipynb

Demonstrates how to capture outputs that are specific to certain Jupyter clients, such as help documentation, which might not be generated by nbconvert.

```python
sorted?
```

--------------------------------

### Initialize Matplotlib and NumPy for Plotting

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/gallery/default-thumbnail.ipynb

Imports necessary libraries for generating plots within a Jupyter notebook. This is a prerequisite for creating image outputs that nbsphinx can use as thumbnails.

```python
import matplotlib.pyplot as plt
import numpy as np
```

--------------------------------

### Embed HTML Audio Element

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/markdown-cells.ipynb

Demonstrates how to embed an audio file using the HTML5 `<audio>` element. This allows for audio playback directly within the HTML output.

```html
<audio src="https://example.org/audio.ogg" controls>alternative text</audio>
```

--------------------------------

### Handling Interactive Inputs

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/pre-executed.ipynb

Shows how to manage code that requires user input. Since Sphinx builds are non-interactive, pre-executing allows you to provide the inputs and save the resulting state.

```python
name = input('What... is your name?')
quest = input('What... is your quest?')
color = input('What... is your favorite color?')
```

--------------------------------

### Run sphinx-autobuild for LaTeX

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/usage.ipynb

Command to configure sphinx-autobuild to generate LaTeX output. Note that PDF generation from LaTeX requires additional tools like latexmk.

```bash
python3 -m sphinx_autobuild <source-dir> <build-dir> -b latex
```

--------------------------------

### Configure ReadTheDocs Build

Source: https://context7.com/spatialaudio/nbsphinx/llms.txt

Defines build environments and dependencies for automatic documentation generation on ReadTheDocs.

```yaml
version: 2
build:
  os: ubuntu-22.04
  tools:
    python: "3.11"
python:
  install:
    - requirements: doc/requirements.txt
formats:
  - pdf
  - epub
```

```text
nbsphinx
ipykernel
matplotlib
numpy
pandas
sphinx>=4.0
```

--------------------------------

### Include Remote Image using Markdown

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/markdown-cells.ipynb

Shows how to embed a remote image using Markdown by providing a URL. This allows for images hosted on external servers to be displayed.

```markdown
![Python logo (remote)](https://www.python.org/static/img/python-logo-large.png)
```

--------------------------------

### Configure Per-Notebook Execution Metadata

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/never-execute.ipynb

Overrides global settings for a specific notebook by embedding execution instructions directly into the notebook's JSON metadata. This allows granular control over which notebooks are executed.

```json
"nbsphinx": {
  "execute": "never"
}
```

--------------------------------

### Compile LaTeX Document with latexmk

Source: https://github.com/spatialaudio/nbsphinx/blob/master/include-in-latex/README.md

Compile the master LaTeX document from the root directory using latexmk, which utilizes the local latexmkrc configuration to resolve file paths.

```bash
latexmk -pv
```

--------------------------------

### Display Pandas DataFrames

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/code-cells.ipynb

Demonstrates how Pandas DataFrames are rendered as formatted HTML tables within the notebook environment.

```python
import numpy as np
import pandas as pd
df = pd.DataFrame(np.random.randint(0, 100, size=[10, 4]),
                  columns=[r'$\alpha$', r'$\beta$', r'$\gamma$', r'$\delta$'])
df
```

--------------------------------

### Create Links in Markdown Cells

Source: https://context7.com/spatialaudio/nbsphinx/llms.txt

Create links between notebooks, documentation files (RST), and sections within the generated output. Links to notebooks and RST files work automatically, and internal section links are supported.

```markdown
<!-- Link to another notebook -->
[See the installation guide](installation.ipynb)

<!-- Link to a section in another notebook -->
[Configuration options](configuration.ipynb#nbsphinx-Configuration-Values)

<!-- Link to an RST file -->
[API Reference](api-reference.rst)

<!-- Link to a section in the current notebook -->
[Back to top](#)

<!-- Reference-style links -->
[installation guide][install]

[install]: installation.ipynb
```

--------------------------------

### reST Link to Notebook

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/orphan.ipynb

Shows how to create a hyperlink to a notebook or other Sphinx source file from a reStructuredText (.rst) file. This allows seamless linking between different documentation formats.

```rst
`some link text <notebookname.ipynb>`__
```

--------------------------------

### Generate Local Thumbnail Image with Matplotlib

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/gallery/thumbnail-from-conf-py.ipynb

This snippet demonstrates how to create a local image file using Matplotlib. The generated file can subsequently be referenced as a thumbnail in the Sphinx configuration.

```python
import matplotlib.pyplot as plt
fig, ax = plt.subplots()
ax.plot([4, 8, 15, 16, 23, 42])
fig.savefig('a-local-file.png')
plt.close()
```

--------------------------------

### Configure Sphinx extensions

Source: https://context7.com/spatialaudio/nbsphinx/llms.txt

Adds nbsphinx and other extensions to the Sphinx configuration file (conf.py). This enables notebook parsing and other functionalities like math rendering and bibliography support. It also excludes Jupyter checkpoint directories from the build.

```python
# conf.py

extensions = [
    'nbsphinx',
    'sphinx.ext.mathjax',  # for math equations
    'sphinxcontrib.bibtex',  # for bibliographic references
]

# Exclude Jupyter checkpoint directories
exclude_patterns = ['_build', '**.ipynb_checkpoints']
```

--------------------------------

### Display pandas DataFrames in Notebooks

Source: https://context7.com/spatialaudio/nbsphinx/llms.txt

Demonstrates how to render pandas DataFrames as formatted HTML tables within a Jupyter notebook environment.

```python
import pandas as pd
df = pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]})
df
```

--------------------------------

### Build LaTeX Output with Sphinx

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/usage.ipynb

Command to generate LaTeX output from Sphinx source files. This output can then be used to create PDF documents.

```bash
python3 -m sphinx <source-dir> <build-dir> -b latex
```

--------------------------------

### Customize Cell Prompts with nbsphinx_input_prompt and nbsphinx_output_prompt

Source: https://context7.com/spatialaudio/nbsphinx/llms.txt

Customize the appearance of code cell input and output prompts. The '%s' placeholder is replaced with the execution count. Empty strings can be used to remove prompts entirely.

```python
# conf.py

# Classic Jupyter-style prompts
bsphinx_input_prompt = 'In [%s]:'
bsphinx_output_prompt = 'Out[%s]:'

# Simple numbered prompts
bsphinx_input_prompt = '[%s]'
bsphinx_output_prompt = '[%s]'

# Remove prompts entirely
bsphinx_input_prompt = ''
bsphinx_output_prompt = ''
```

--------------------------------

### Display Image in Python using IPython

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/subdir/a-notebook-in-a-subdir.ipynb

This Python code snippet uses the IPython.display module to render an image from a specified file path. It's useful for displaying images within Jupyter notebooks or similar environments. Ensure the image file exists at the provided relative path.

```python
from IPython.display import Image
Image(filename='../images/notebook_icon.png')
```

--------------------------------

### Create Thumbnail Galleries using .. nbgallery:: directive

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/a-normal-rst-file.rst

This reStructuredText directive, nbgallery, allows the creation of thumbnail galleries directly within reST files. It accepts parameters similar to the Sphinx toctree directive and is useful for organizing and showcasing notebooks.

```rst
.. nbgallery::
    :caption: This is a thumbnail gallery:
    :name: rst-gallery
    :glob:
    :reversed:

    gallery/*-rst
```

--------------------------------

### Support Custom Notebook Formats with nbsphinx_custom_formats

Source: https://context7.com/spatialaudio/nbsphinx/llms.txt

Enable support for custom notebook formats by defining converter functions. This allows nbsphinx to process notebooks stored in alternative formats like Jupytext's percent format or R-Markdown files.

```python
# conf.py

# Support Jupytext percent format
bsphinx_custom_formats = {
    '.pct.py': ['jupytext.reads', {'fmt': 'py:percent'}],
}

# Support R-Markdown files
bsphinx_custom_formats = {
    '.Rmd': ['jupytext.reads', {'fmt': 'Rmd'}],
}

# Support multiple formats
bsphinx_custom_formats = {
    '.pct.py': ['jupytext.reads', {'fmt': 'py:percent'}],
    '.md': ['jupytext.reads', {'fmt': 'Rmd'}],
}
```

--------------------------------

### Control Image Size with HTML img Tag

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/markdown-cells.ipynb

Illustrates how to use the HTML `<img>` tag to include an image and control its size using the `width` attribute. This method provides more control than standard Markdown.

```html
<img src="images/notebook_icon.png" alt="Jupyter notebook icon" width="300">
```

--------------------------------

### Create Info and Warning Boxes

Source: https://context7.com/spatialaudio/nbsphinx/llms.txt

Uses HTML div elements with specific CSS classes to create styled admonition boxes in Markdown cells.

```html
<div class="alert alert-info">
**Note**
This is an informational note.
</div>

<div class="alert alert-warning">
**Warning**
This is a warning message.
</div>
```

--------------------------------

### Configure Global Notebook Execution in conf.py

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/never-execute.ipynb

Sets the global execution policy for all notebooks processed by nbsphinx. Setting this to 'never' prevents automatic execution of notebook cells during the build process.

```python
nbsphinx_execute = 'never'
```

--------------------------------

### Embedding JavaScript with nbsphinx

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/code-cells.ipynb

This snippet demonstrates how to execute arbitrary JavaScript code within a Jupyter Notebook cell using the %%javascript magic command. The output is appended to a designated HTML element, making it visible in the notebook output.

```python
%%javascript

var text = document.createTextNode("Hello, I was generated with JavaScript!");
// Content appended to "element" will be visible in the output area:
element.appendChild(text);
```

--------------------------------

### Configure Sphinx MathJax Extensions

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/markdown-cells.ipynb

Configures the Sphinx extensions to enable MathJax support for rendering LaTeX equations in HTML output. This is required for equations to display correctly.

```python
extensions = [
    'nbsphinx',
    'sphinx.ext.mathjax',
    # ... other useful extensions ...
]
```

--------------------------------

### Render Markdown with IPython

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/code-cells.ipynb

Uses IPython.display.Markdown to render formatted text, links, images, LaTeX equations, and tables within the notebook output.

```python
from IPython.display import Markdown
md = Markdown("""
# Markdown
It *should* show up as **formatted** text
with things like [links] and images.
[links]: https://jupyter.org/
![Jupyter notebook icon](images/notebook_icon.png)
## Markdown Extensions
There might also be mathematical equations like
$a^2 + b^2 = c^2$
and even tables:

A     | B     | A and B
------|-------|--------
False | False | False
True  | False | False
False | True  | False
True  | True  | True
""")
md
```

--------------------------------

### Configure nbsphinx and sphinxcontrib.bibtex in conf.py

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/a-normal-rst-file.rst

This Python code snippet shows how to enable the nbsphinx and sphinxcontrib.bibtex extensions and specify BibTeX files in Sphinx's configuration file (conf.py). It's essential for managing citations within Sphinx projects that use Jupyter notebooks.

```python
extensions = [
    'nbsphinx',
    'sphinxcontrib.bibtex',
    # Probably more extensions here ...
]

bibtex_bibfiles = ['my-references.bib']
bibtex_reference_style = 'author_year'
```

--------------------------------

### Configure Matplotlib for Notebooks

Source: https://context7.com/spatialaudio/nbsphinx/llms.txt

Configures Matplotlib to generate high-quality plots for both HTML and LaTeX outputs by setting figure formats and DPI.

```python
import matplotlib.pyplot as plt
import numpy as np

x = np.linspace(0, 10, 100)
fig, ax = plt.subplots(figsize=[6, 3])
ax.plot(x, np.sin(x), label='sin(x)')
ax.plot(x, np.cos(x), label='cos(x)')
ax.legend()
ax.set_xlabel('x')
ax.set_ylabel('y')
plt.show()
```

```python
nbsphinx_execute_arguments = [
    "--InlineBackend.figure_formats={'svg', 'pdf'}",
]
```

```text
figure.dpi: 96
```

--------------------------------

### Handle Long-Running Computations

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/pre-executed.ipynb

Demonstrates how to perform time-consuming operations in a notebook. By pre-executing, you avoid re-running these tasks during every Sphinx build.

```python
import time
%time time.sleep(60 * 60)
6 * 7
```

--------------------------------

### Linking to Notebooks with :ref: Directive

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/a-normal-rst-file.rst

Illustrates linking to local notebook files using the Sphinx :ref: directive. This method allows for automatic extraction of section titles as link text or custom link text. Note that :ref: links are specific to Sphinx and may not render correctly on platforms like GitHub.

```rst
:ref:`/subdir/a-notebook-in-a-subdir.ipynb`
```

```rst
:ref:`your own link title </subdir/a-notebook-in-a-subdir.ipynb>`
```

```rst
:ref:`/subdir/a-notebook-in-a-subdir.ipynb#A-Sub-Section`
:ref:`alternative text </subdir/a-notebook-in-a-subdir.ipynb#A-Sub-Section>`
```

--------------------------------

### Linking to Notebooks with RST

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/a-normal-rst-file.rst

Demonstrates how to create hyperlinks to local notebook files within reStructuredText (RST) documents using relative paths. Supports standard Sphinx hyperlinks, backticks for spaces in link text, anonymous hyperlink targets, and embedded URIs. These links are designed to work in both Sphinx and other RST renderers like GitHub.

```rst
using a relative path to the local file: link_.

.. _link: subdir/a-notebook-in-a-subdir.ipynb
```

```rst
surround it with backticks: `a notebook link`_.

.. _a notebook link: subdir/a-notebook-in-a-subdir.ipynb
```

```rst
like this: link__.

__ subdir/a-notebook-in-a-subdir.ipynb
```

```rst
like this `link <subdir/a-notebook-in-a-subdir.ipynb>`__.
```

```rst
For example, see this subsection_.

.. _subsection: subdir/a-notebook-in-a-subdir.ipynb#A-Sub-Section
```

--------------------------------

### HTML Structure for Jupyter Widgets

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/code-cells.ipynb

This HTML snippet illustrates the necessary script tags for loading Jupyter widgets. It includes require.js, the @jupyter-widgets/html-manager embed script, and a custom embed-widgets.js if custom widgets are used. The order of these scripts is crucial for correct widget rendering.

```html
<!-- require.js is a mandatory dependency for jupyter-widgets -->
<script crossorigin="anonymous" integrity="sha256-Ae2Vz/4ePdIu6ZyI/5ZGsYnb+m0JlOmKPjt6XZ9JJkA=" src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"></script>
<!-- jupyter-widgets JavaScript -->
<script type="text/javascript" src="https://unpkg.com/@jupyter-widgets/html-manager@^0.18.0/dist/embed-amd.js"></script>
<!-- JavaScript containing custom Jupyter widgets -->
<script src="../_static/embed-widgets.js"></script>
```

--------------------------------

### Configure Sphinx Extensions

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/usage.ipynb

This snippet shows how to add 'nbsphinx' to the extensions list in Sphinx's configuration file (conf.py). This is essential for nbsphinx to process Jupyter notebooks.

```python
extensions = [
    'nbsphinx',
]
```

--------------------------------

### Generate Multiple Cell Outputs

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/gallery/multiple-outputs.ipynb

This Python code demonstrates a cell with multiple display outputs. By using the metadata from the previous snippet, the third output (the Python logo) would be selected as the thumbnail.

```python
from IPython.display import Image

display(Image(url='https://jupyter.org/assets/homepage/main-logo.svg'))
print('Hello!')
display(Image(filename='../images/notebook_icon.png'))
display(Image(url='https://www.python.org/static/img/python-logo-large.png', embed=True))
```

--------------------------------

### Displaying Basic ANSI Colors in Python

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/code-cells.ipynb

This Python code snippet generates output with basic ANSI escape sequences to demonstrate text and background color changes. It iterates through foreground and background color codes, including bold variations, to showcase their effects.

```python
import sys

print('BEWARE: \x1b[1;33;41mugly colors\x1b[m!', file=sys.stderr)
print('AB\x1b[43mCD\x1b[35mEF\x1b[1mGH\x1b[4mIJ\x1b[7m'
      'KL\x1b[49mMN\x1b[39mOP\x1b[22mQR\x1b[24mST\x1b[27mUV')

text = ' XYZ '
formatstring = '\x1b[{}m' + text + '\x1b[m'

print(' ' * 6 + ' ' * len(text) +
      ''.join('{:^{}}'.format(bg, len(text)) for bg in range(40, 48)))
for fg in range(30, 38):
    for bold in False, True:
        fg_code = ('1;' if bold else '') + str(fg)
        print(' {:>4} '.format(fg_code) + formatstring.format(fg_code) +
              ''.join(formatstring.format(fg_code + ';' + str(bg))
                      for bg in range(40, 48)))
```

--------------------------------

### Configure Sphinx for Custom CSS

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/custom-css.ipynb

This configuration in conf.py tells Sphinx to include custom CSS files from the '_static' directory. It requires setting both html_static_path and html_css_files.

```python
html_static_path = ['_static']
html_css_files = ['my-own-style.css']
```

--------------------------------

### nbsphinx Info and Warning Boxes

Source: https://github.com/spatialaudio/nbsphinx/blob/master/doc/a-normal-rst-file.rst

Shows the usage of custom reStructuredText directives `nbinfo` and `nbwarning` provided by nbsphinx for creating informational and warning boxes within documentation. These are experimental features intended for future integration with Markdown cells.

```rst
.. nbwarning::
    Warning

    This is an experimental feature!
    Its usage may change in the future or it might disappear completely, so
    don't use it for now.
```

```rst
.. nbinfo::
    Note

    This is an info box.

    It may include nested formatting, even another info/warning box:

    .. nbwarning:: **Warning:** You should probably not use nested boxes!
```

--------------------------------

### Include notebooks in Sphinx toctree

Source: https://context7.com/spatialaudio/nbsphinx/llms.txt

Demonstrates how to include Jupyter notebooks within the Sphinx documentation's table of contents (toctree). Notebooks are referenced without their file extension and are treated like regular RST files for navigation and cross-referencing.

```rst
.. toctree::
   :maxdepth: 2
   :caption: Contents

   installation
   usage
   my-notebook
   subdir/another-notebook
```

--------------------------------

### Enable Math Equation Numbering with mathjax3_config

Source: https://context7.com/spatialaudio/nbsphinx/llms.txt

Enable automatic equation numbering for LaTeX math equations rendered in the documentation. This configuration is done within the Sphinx configuration file (conf.py).

```python
# conf.py - Enable automatic equation numbering
mathjax3_config = {
    'tex': {'tags': 'ams', 'useLabelIds': True},
}
```

--------------------------------

### Control build continuation on errors

Source: https://context7.com/spatialaudio/nbsphinx/llms.txt

Configures nbsphinx_allow_errors in conf.py to determine whether the Sphinx build process should continue if notebook execution encounters errors. When True, the build proceeds, and errors are included in the output.

```python
# conf.py

# Stop build on errors (default)
bsphinx_allow_errors = False

# Continue build despite errors
bsphinx_allow_errors = True
```