Add session mode section in ark --help#1316
Conversation
DavisVaughan
left a comment
DavisVaughan
left a comment
There was a problem hiding this comment.
Fine, but I do think we should not put the extended docs in the CLI output itself
| Session modes: | ||
|
|
||
| "console" mode (the default) is meant for a rich frontend like Positron, while | ||
| "notebook" mode is meant for standard Jupyter frontends. They differ in how | ||
| some output is reported to the frontend: | ||
|
|
||
| - Errors. A Jupyter error message carries the error message in "evalue" and the | ||
| backtrace in "traceback". In "console" mode these are sent as-is. In | ||
| "notebook" mode the error message is also prepended to "traceback", because | ||
| frontends such as JupyterLab only display "traceback" when it is present, | ||
| discarding "evalue". Without the prepend the error message wouldn't show at | ||
| all. | ||
|
|
||
| - Autoprint of intermediate expressions. When a single request contains several | ||
| top-level expressions (e.g. `a` and `b` in `a; b; c`), "console" mode streams | ||
| each intermediate result to the frontend, matching R behaviour. "notebook" | ||
| mode emits only the last expression's result, matching how a notebook cell is | ||
| typically evaluated by Jupyter kernels. | ||
|
|
||
| Note that `ark --install` sets the generated kernelspec to run Ark in notebook | ||
| mode. |
There was a problem hiding this comment.
I think CLI help should be relatively quiet, reporting just the options available with a brief description about them. If we started adding these extra docs about each option, our --help output would get way too long imo.
This feels like it should be in Ark website documentation somewhere. For lack of a better place, maybe a new Ark CLI section of https://github.com/posit-dev/ark/blob/main/doc/configuration.md
I feel like this is especially true here, with these extremely niche details that are better left to more in depth docs, rather than the first thing a user sees when requesting help with --help
2 participants
Closes #1311