Quarto Cell Options Specification

[hguturu]

What would you like to do?

Understand the quarto markdown format better to implement in python code formatting support in nbqa.

Description

I am trying to implement quarto support in nbqa - nbQA-dev/nbQA#881 for allowing python code formatters to work on qmd files. I was wondering if there is some details on the #| conventions?

For example, if the I have the following file:

test1.qmd

```{python}
#| label: fig-polar
#| fig-cap: A line plot on a polar axis
```

The the following steps yield expected results:

quarto convert --log-level warnings test1.qmd && mv test1.ipynb test1cp.ipynb
quarto convert --log-level warnings test1cp.ipynb
sdiff -s test1.qmd test1cp.qmd
                                                              > ---
                                                              > jupyter: python3
                                                              > ---
                                                              > 
                                                              > 

But, if I have this other file:

test2.qmd

```{python}
#| label: fig-polar
#| fig-cap: A line plot on a polar axis
# |  Should not be changed back to #|
```

The the following steps yield expected results:

quarto convert --log-level warnings test2.qmd && mv test2.ipynb test2cp.ipynb
quarto convert --log-level warnings test2cp.ipynb
sdiff -s test2.qmd test2cp.qmd
                                                              > ---
                                                              > jupyter: python3
                                                              > ---
                                                              > 
#| fig-cap: A line plot on a polar axis                       | #| fig-cap: |-
# |  Should not be changed back to #|                         | #|   A line plot on a polar axis
                                                              > #|   Should not be changed back to
                                                              > 

This suggests that my understanding of the #| convention is not correct. Cell options can be multi-line? Are # | (with space) also valid cell options as #| (without space)?

This leads me to other questions about the qmd format. For example, in my support for the markdown processing, I look for {python} - https://github.com/nbQA-dev/nbQA/pull/881/files#diff-d72c6dc865400b582f957459d2f13e4030da8a9f8afdec522def74313d29a25fR137, but is that sufficiently robust? Do I need to look for something else?

[mcanouil]

Please use discussion for discussion/question.

Python formatter does add a space after comment symbol, thus Quarto allows both for Python.