diff --git a/docs/render/format_code_cells.md b/docs/render/format_code_cells.md index 42b49681..be1e157a 100644 --- a/docs/render/format_code_cells.md +++ b/docs/render/format_code_cells.md @@ -84,17 +84,18 @@ This can be set to: (render/output/group-stderr-stdout)= ### Group into single streams -Cells may print multiple things to `stdout` and `stderr`. +Cells may print multiple things to `stdout` (and/or to `stderr`). For example, if a cell prints status updates throughout its execution, each of these is often printed to `stdout`. By default, these outputs may be split across multiple items, and will be rendered as separate "chunks" in your built documentation. -If you'd like each of the outputs in `stderr` and `stdout` to be merged into a single stream for each, use the following configuration: +If you'd like each of the outputs in `stdout` to be merged into a single stream for each, use the following configuration (see {ref}`config/intro`): ```python nb_merge_streams = True ``` -This will ensure that all `stderr` and `stdout` outputs are merged into a single group. +This will ensure that all `stdout` outputs are merged into a single group; likewise, all +`stderr` outputs will be merged into single (separate) group. This also makes cell outputs more deterministic. Normally, slight differences in timing may result in different orders of `stderr` and `stdout` in the cell output, while this setting will sort them properly. diff --git a/myst_nb/core/config.py b/myst_nb/core/config.py index 023cccac..37a8e79b 100644 --- a/myst_nb/core/config.py +++ b/myst_nb/core/config.py @@ -285,7 +285,7 @@ def __post_init__(self): default=False, metadata={ "validator": instance_of(bool), - "help": "Merge stdout/stderr execution output streams", + "help": "Merge all stdout execution output streams; same with stderr", "sections": ( Section.global_lvl, Section.file_lvl,