docs(sample): document the progressbar_theme parameter

[adv0r]

AI disclaimer: Authored, tested, and verified by an AI agent (Claude Opus 4.7 via Cursor) operating unattended as a personal token-burn initiative by @adv0r before subscription renewal. Not human-reviewed before submission. The agent read the issue, the public `pm.sample()` signature in `pymc/sampling/mcmc.py` (3 overloads + the implementation), and the actual call sites of `progressbar_theme` in `pymc/progress_bar/progress.py`, `pymc/progress_bar/rich_progress.py`, and `pymc/backends/arviz.py` to verify the documented behaviour matches what the code does.

What changed

Closes #7468.

pm.sample(progressbar_theme=...) was a public, type-annotated parameter (Theme | str | None) but missing from the docstring. This PR adds a complete progressbar_theme entry to the pm.sample docstring, directly after the existing progressbar entry, covering:

• The three accepted forms:
  • None (default) → fall back to PyMC's built-in default_progress_theme (the PyMC-blue `#1764f4` bar).
  • A `rich.theme.Theme` instance → used as-is to style the underlying `rich.console.Console` / `rich.progress.Progress`.
  • A `str` → forwarded as `css_theme` for nutpie's Jupyter progress bar.
• Which `rich` theme keys users typically want to override (`bar.complete`, `bar.finished`, `bar.pulse`, `progress.remaining`, `progress.elapsed`) — the same keys that the default theme actually sets.
• The conditions under which the argument is silently ignored (`progressbar=False`, `quiet=True`, or `nuts_sampler` is `numpyro` / `blackjax` — those samplers don't render their own rich-styled progress bar).
• A short worked example.

Diff: 1 file changed, 40 insertions(+). Documentation-only.

How verified

• AST-parsed pymc/sampling/mcmc.py after the edit to make sure the docstring stays a valid string literal.
• Cross-checked the documented behaviour against the actual implementation:
  • pymc/progress_bar/rich_progress.py:35 — default_progress_theme definition, including the #1764f4 bar colour I reference in the example.
  • pymc/progress_bar/progress.py:181-195 — the branch that uses css_theme=... when the theme is a str (Jupyter / nutpie), vs. the Theme branch.
  • pymc/sampling/mcmc.py:505-530 — the numpyro / blackjax branch, which does not forward progressbar_theme (justifying the "ignored when nuts_sampler is numpyro/blackjax" sentence).
  • pymc/sampling/mcmc.py:1607-1610 — the existing terse docstring for the internal _mp_sample function, which I left untouched (only the public API needed expansion per the issue).
• Sanity-checked the Sphinx-style rST inside the docstring (``.. code-block:: python``, ``:class:`rich.theme.Theme```, bullet list indentation).

Out of scope

• The issue reporter also asks about getting "[sampled/total] display back" — that's about progress-bar columns, not themes. It is a separate ask and would touch `make_tasks_table` / column construction, not the documentation of an existing public parameter. Happy to file a follow-up issue if maintainers want one, but keeping this PR scoped to what DOC: progressbar_theme is undocumented #7468 actually says.
• Not touching the internal terse docstring for `_mp_sample` at `mcmc.py:1607-1610`. It's internal and already mentions `progressbar_theme`.

Made with Cursor

[read-the-docs-community]

Documentation build overview

📚 pymc | 🛠️ Build #32774862 | 📁 Comparing 08cbdd6 against latest (853149c)

  🔍 Preview build  

3 files changed

± glossary.html
± api/generated/pymc.sample.html
± _modules/pymc/sampling/mcmc.html