docs: example code block notes

[machow]

Addresses

• Doc suggestion: show output, and include code block examples that don't evaluate code #219

[machow]

@wch does this note below the code example look okay?

[wch]

I think it's still a bit unclear what happens when the quarto code block executed. Does it include the output as well, and how is it all formatted?

For example, I could imagine that it looks like this when executed:

>>> 1 + 1
2

Or maybe it just executes it and prints the output, like this:

2

Or maybe the code and output are in two separate blocks:

1 + 1

2

Currently, the reader would have to actually test it out in order to find out what the output would look like -- it would be much better to show what it would do.

[wch]

One more quick thought: I know that Quarto does allow customization to the output. So maybe show what the default behavior is, and then point the reader to the Quarto docs for controlling the output behavior if they want to customize it.

[machow]

I've tinkered a bit more, and think I remember the big challenge was with showing results for these examples.

Basically, quarto is absolutely nuts when it comes to...

• representing qmd content in a python string
• correctly showing notebook code / output that seems like it contains qmd syntax

For example this is how I got quarto to not error for the example:

from griffe.docstrings import Parser
from griffe.dataclasses import Docstring

from quartodoc.renderers import MdRenderer

# Note the nuts string combining
# to create the phrase "```python```"
# or the phrase "{python}
doc = """
    Examples
    --------
    
    doctest syntax:
    
    >>> 1 + 1
    2
    
    markdown syntax:
    
    """ "```" "python" """
    1 + 1
    ```
    
    quarto syntax:
    
    ```""" "{" "python" "}" """
    1 + 1
    ```
"""

ds = Docstring(doc, parser = Parser("numpy"))
rendered = MdRenderer().render(ds)

print(rendered)

Here's what gets printed out on the page:

::: {.cell execution_count=1}
```` {.python .cell-code}
from griffe.docstrings import Parser
from griffe.dataclasses import Docstring

from quartodoc.renderers import MdRenderer

the_word_python = "python"

# you can't use single curly braces or quarto tries to make
# a new code block, so we use an f-string with double braces
doc = """
Examples
--------

doctest syntax:

>>> 1 + 1
2

markdown syntax:

""" "```" "python" """
1 + 1
```


quarto syntax:

```""" "{" "python" "}"
1 + 1
````

::: {.cell-output .cell-output-display execution_count=14}
```
2
```
:::
:::
““”

ds = Docstring(doc, parser = Parser(“numpy”)) rendered = MdRenderer().render(ds)

print(rendered)

Note that the result of print(rendered) isn't even shown. It seems like something is seriously broken (at a glance, that quarto very aggressively looks for code blocks? Even in echos / output?).

Seems related to quarto-dev/quarto-cli#3179

[machow]

I mean that the weirdness literally appears on the page

edit:

here's the relevant part from setting keep-md: true in the top-matter:

Here is a rendererd example of the above code:


    ::: {.cell execution_count=1}
    ```` {.python .cell-code}
    from griffe.docstrings import Parser
    from griffe.dataclasses import Docstring
    
    from quartodoc.renderers import MdRenderer
    
    the_word_python = "python"
    
    # you can't use single curly braces or quarto tries to make
    # a new code block, so we use an f-string with double braces
    doc = """
    Examples
    --------
    
    doctest syntax:
    
    >>> 1 + 1
    2
    
    markdown syntax:
    
    """ "```" "python" """
    1 + 1
    ```
    
    
    quarto syntax:
    
    ```""" "{" "python" "}"
    1 + 1
    ````
    
    ::: {.cell-output .cell-output-display execution_count=1}
    ```
    2
    ```
    :::
    :::
    
    
"""

ds = Docstring(doc, parser = Parser("numpy"))
rendered = MdRenderer().render(ds)

print(rendered)
```