Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

Fix documentation and argument-parsing for thumbnails export (#8301)

Julien Lehuen61699c37b759
diff --git a/docs/guides/publishing/opengraph.md b/docs/guides/publishing/opengraph.md
index 52fcede0ff..4b63acd16a 100644
--- a/docs/guides/publishing/opengraph.md
+++ b/docs/guides/publishing/opengraph.md
@@ -46,8 +46,8 @@ __marimo__/assets/<notebook_stem>/opengraph.png
To generate these thumbnails, use:
```bash
-marimo tools thumbnails generate notebook.py
-marimo tools thumbnails generate folder/
+marimo export thumbnail notebook.py
+marimo export thumbnail folder/
```
For execution and sandbox options (and for Playwright installation instructions), see [Thumbnails](thumbnails.md).
diff --git a/docs/guides/publishing/thumbnails.md b/docs/guides/publishing/thumbnails.md
index 954d2fb79f..2b29e92fa4 100644
--- a/docs/guides/publishing/thumbnails.md
+++ b/docs/guides/publishing/thumbnails.md
@@ -3,7 +3,8 @@
Generate screenshot-based thumbnail images for notebooks, used by [OpenGraph previews](opengraph.md) and cards in [gallery mode](../apps.md#gallery-mode).
```bash
-marimo export thumbnail generate notebook.py
+marimo export thumbnail notebook.py
+```
## Output location
@@ -31,13 +32,13 @@ This is the default OpenGraph thumbnail path used by [OpenGraph previews](opengr
You can generate a thumbnail for a single notebook:
```bash
-marimo tools thumbnails generate notebook.py
+marimo export thumbnail notebook.py
```
Or generate thumbnails for all notebooks in a directory:
```bash
-marimo tools thumbnails generate folder/
+marimo export thumbnail folder/
```
When you pass a directory, marimo scans it for marimo notebooks and skips non-notebook files (for example `README.md`).
@@ -49,19 +50,19 @@ By default, thumbnails are generated without executing the notebook (fast; no ou
=== "No execution (default)"
```bash
- marimo tools thumbnails generate notebook.py
+ marimo export thumbnail notebook.py
```
=== "Execute notebook"
```bash
- marimo tools thumbnails generate notebook.py --execute
+ marimo export thumbnail --execute notebook.py
```
=== "Execute in a sandbox"
```bash
- marimo tools thumbnails generate notebook.py --execute --sandbox
+ marimo export thumbnail --execute --sandbox notebook.py
```
!!! note "Requires uv"
@@ -81,13 +82,13 @@ By default, thumbnails are generated without executing the notebook (fast; no ou
If a thumbnail already exists, marimo will skip it by default. To replace existing thumbnails:
```bash
-marimo tools thumbnails generate notebook.py --overwrite
+marimo export thumbnail --overwrite notebook.py
```
To write a thumbnail to a specific filename, use `--output` (single notebook only):
```bash
-marimo tools thumbnails generate notebook.py --output thumbnail.png
+marimo export thumbnail --output thumbnail.png notebook.py
```
## Tuning quality
@@ -97,13 +98,13 @@ For OpenGraph previews, the default viewport size is 1200x630. marimo also uses
To increase output resolution, increase `--scale` (max 4):
```bash
-marimo tools thumbnails generate notebook.py --scale 3
+marimo export thumbnail --scale 3 notebook.py
```
If thumbnails appear blank or partially rendered, increase `--timeout-ms` to wait longer before the screenshot:
```bash
-marimo tools thumbnails generate notebook.py --timeout-ms 3000
+marimo export thumbnail --timeout-ms 3000 notebook.py
```
## Passing arguments to notebooks
@@ -111,7 +112,7 @@ marimo tools thumbnails generate notebook.py --timeout-ms 3000
To pass CLI args through to the notebook, separate them with `--`:
```bash
-marimo tools thumbnails generate notebook.py -- --foo 123
+marimo export thumbnail notebook.py -- --foo 123
```
For more on passing values to notebooks, see [Command Line Arguments](../../api/cli_args.md).
diff --git a/marimo/_cli/export/thumbnail.py b/marimo/_cli/export/thumbnail.py
index 31af79b963..178565bfe0 100644
--- a/marimo/_cli/export/thumbnail.py
+++ b/marimo/_cli/export/thumbnail.py
@@ -37,17 +37,6 @@ _sandbox_message = (
_READINESS_WAIT_TIMEOUT_MS = 30_000
-def _split_paths_and_args(
- name: str, args: tuple[str, ...]
-) -> tuple[list[str], tuple[str, ...]]:
- paths = [name]
- for index, arg in enumerate(args):
- if arg == "--":
- return paths, args[index + 1 :]
- paths.append(arg)
- return paths, ()
-
-
def _collect_notebooks(paths: Iterable[Path]) -> list[MarimoPath]:
notebooks: dict[str, MarimoPath] = {}
@@ -531,8 +520,7 @@ def thumbnail(
) from None
raise
- paths, notebook_args = _split_paths_and_args(str(name), args)
- notebooks = _collect_notebooks([Path(p) for p in paths])
+ notebooks = _collect_notebooks([Path(name)])
if not notebooks:
raise click.ClickException("No marimo notebooks found.")
if output is not None and len(notebooks) > 1:
@@ -562,7 +550,7 @@ def thumbnail(
overwrite=overwrite,
include_code=include_code,
execute=execute,
- notebook_args=notebook_args,
+ notebook_args=args,
continue_on_error=continue_on_error,
sandbox=sandbox_mode is not None,
)
diff --git a/tests/_cli/test_cli_export.py b/tests/_cli/test_cli_export.py
index 4f88adfc9d..37d8ee5286 100644
--- a/tests/_cli/test_cli_export.py
+++ b/tests/_cli/test_cli_export.py
@@ -10,8 +10,9 @@ import sys
import time
from os import path
from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
+import click
import pytest
from marimo._dependencies.dependencies import DependencyManager
@@ -860,3 +861,92 @@ class TestExportPDF:
stderr = p.stderr.decode()
assert "nbconvert" in stderr
assert "pip install" in stderr
+
+
+ not DependencyManager.playwright.has(),
+ reason="This test requires playwright.",
+)
+class TestExportThumbnail:
+ def test_export_thumbnail(self, temp_marimo_file: str) -> None:
+ p = _run_export("thumbnail", temp_marimo_file)
+ _assert_success(p)
+
+ def test_export_thumbnail_with_args(self, temp_marimo_file: str) -> None:
+ p = _run_export("thumbnail", temp_marimo_file, "--", "--foo", "123")
+ _assert_success(p)
+
+
+class TestClickArgsParsing:
+ """
+ Tests below are technically testing Click more than Marimo. This was created as part of an investigation into
+ the Click option to allow interspersed arguments or not, and the presence of "--" in the `args` parameter.
+
+ In review, we discussed leaving some of the tests behind to continue illustrating. They can also act as a sort of
+ sandbox to try alternative approaches.
+ """
+
+ @staticmethod
+ def _params(
+ command, expected_name, expected_args, expected_opt
+ ) -> tuple[Any, ...]:
+ return pytest.param(
+ command,
+ expected_name,
+ expected_args,
+ expected_opt,
+ id=f"`test_command {' '.join(command)}`",
+ )
+
+ @pytest.mark.parametrize(
+ (
+ "command",
+ "expected_name",
+ "expected_args",
+ "expected_opt",
+ ),
+ [
+ _params(["nb.py"], "nb.py", (), False),
+ _params(["--opt", "nb.py"], "nb.py", (), True),
+ _params(["nb.py", "--opt"], "nb.py", (), True),
+ _params(
+ ["nb.py", "--", "--foo", "123"],
+ "nb.py",
+ ("--foo", "123"),
+ False,
+ ),
+ _params(
+ ["--opt", "nb.py", "--", "--foo", "123"],
+ "nb.py",
+ ("--foo", "123"),
+ True,
+ ),
+ _params(
+ ["nb.py", "--opt", "--", "--foo", "123"],
+ "nb.py",
+ ("--foo", "123"),
+ True,
+ ),
+ ],
+ )
+ def test_click_args_parsing(
+ self,
+ command: list[str],
+ expected_name: str,
+ expected_args: tuple[str, ...],
+ expected_opt: bool,
+ ) -> None:
+ @click.command("test_command")
+ @click.argument("name")
+ @click.option("--opt/--no-opt", default=False)
+ @click.argument("args", nargs=-1, type=click.UNPROCESSED)
+ def test_command(
+ name: str, opt: bool, args: tuple[str, ...]
+ ) -> tuple[str, tuple[str, ...], bool]:
+ return name, args, opt
+
+ assert test_command.main(command, standalone_mode=False) == (
+ expected_name,
+ expected_args,
+ expected_opt,
+ )