From 08cbdd6e4f148af388812ef26a42532904148eec Mon Sep 17 00:00:00 2001
From: adv0r <advanced@cursor.local>
Date: Wed, 20 May 2026 13:04:41 +0200
Subject: [PATCH] docs(sample): document the progressbar_theme parameter
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`pm.sample(progressbar_theme=...)` has been a public, type-annotated
parameter for a while (`Theme | str | None`) but it was missing from
the docstring entirely, so users had no way to discover it short of
reading the source.

This commit adds a `progressbar_theme` entry to the docstring of
`pm.sample` directly after the existing `progressbar` entry, covering:

- the three accepted forms (`None` → default theme, `rich.theme.Theme`
  instance → custom rich styling, `str` → nutpie CSS theme name for
  Jupyter),
- where the default theme lives (`pymc.progress_bar.default_progress_theme`
  and its PyMC-blue `#1764f4` bar color),
- which `rich` theme keys are the ones users normally want to override
  (`bar.complete`, `bar.finished`, `bar.pulse`, `progress.remaining`,
  `progress.elapsed`),
- the conditions under which the argument is silently ignored
  (`progressbar=False`, `quiet=True`, `nuts_sampler` is `numpyro` /
  `blackjax`),
- a small worked example.

No behaviour change — purely a docstring addition.

Closes #7468

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 pymc/sampling/mcmc.py | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/pymc/sampling/mcmc.py b/pymc/sampling/mcmc.py
index 3b2cb464e2..8fb4295cc7 100644
--- a/pymc/sampling/mcmc.py
+++ b/pymc/sampling/mcmc.py
@@ -674,6 +674,46 @@ def sample(
                 are also displayed.
 
             If True, the default is "split+stats" is used.
+    progressbar_theme : rich.theme.Theme or str, optional
+        How to style the live progress bar that the ``pymc`` and ``nutpie`` samplers
+        render through `rich <https://rich.readthedocs.io/>`_. Three kinds of values
+        are accepted:
+
+        - ``None`` (default) — fall back to PyMC's built-in theme
+          (``pymc.progress_bar.default_progress_theme``), which paints the bar in
+          PyMC blue (``#1764f4``).
+        - A :class:`rich.theme.Theme` instance — used as-is to construct the
+          underlying :class:`rich.console.Console` and :class:`rich.progress.Progress`
+          objects. Keys you typically want to override are ``bar.complete``,
+          ``bar.finished``, ``bar.pulse``, ``progress.remaining`` and
+          ``progress.elapsed``.
+        - A string — passed straight through as ``css_theme`` when sampling inside
+          a Jupyter notebook (`nutpie` only). This lets you reuse the CSS theme
+          name that ``nutpie`` ships, for example to match a dark-mode notebook.
+
+        The argument is ignored entirely when ``progressbar=False``, when
+        ``quiet=True``, and when the selected ``nuts_sampler`` does not render
+        its own progress bar (``numpyro`` and ``blackjax``).
+
+        Example:
+
+        .. code-block:: python
+
+            from rich.theme import Theme
+            import pymc as pm
+
+            my_theme = Theme(
+                {
+                    "bar.complete": "magenta",
+                    "bar.finished": "magenta",
+                    "progress.remaining": "dim",
+                }
+            )
+
+            with pm.Model():
+                pm.Normal("x")
+                idata = pm.sample(progressbar_theme=my_theme)
+
     quiet : bool, default False
         If True, suppress all logging output and progress bars during sampling.
         This is useful when sampling in loops or when no output is desired.