[discussion]: how do we want to display docstring examples in the reference docs?

[signekb]

We'll be using the Quarto syntax, so the code will be executed:

```{python}
code here
```

But some decisions are still to be made before I can add the docstrings examples in #951:

• Do we want the output of the code to be shown or hidden?
• Do we want separate code blocks for each example or collect them in one block?

Option 1: One code block + Hidden output

Option 2: One code block + Shown output

(No good: Only last output shown)

Option 3: Separate code blocks + Hidden output

Option 4: Separate code blocks + Shown output

What do you think @seedcase-project/developers ?

[lwjohnst86]

Ah, strange that there isn't an option to have same code block but also show both outputs (option 2 doesn't show the output of the second command).

We should show the output.

[signekb]

Yeah, really strange. I at least couldn't find a workaround to include all outputs. It might also be nicer, actually, if the output is longer/more complex, to keep them separate?

[signekb]

Option 4 it is: Separate code blocks with shown output