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.

[hguturu]

Ok, perfect, that makes life easier for me. I thought the formatters converting '#|' to '# |' broke cell options, but if quarto supports both '#|' and '# |' then, no special handling is needed on the nbqa side.

But, it would still be good to have a specification file for the format.

Is looking for {python} a valid way to look for python code blocks or is a wider range of syntax allowed to demarcate python code blocks?

[hguturu]

Also nothing below comment by @mcanouil

Brackets is for "code cell" meaning computation.
No brackets or dot languages are code blocks with syntax highlighting thus no computation.

[hguturu]

I was going based on https://quarto.org/docs/computations/inline-code.html, but some of the examples here https://quarto.org/docs/authoring/markdown-basics.html#source-code suggest otherwise. Perhaps the latter set is just for code formatting, but not for executable blocks and will be handled by a normal markdown parser?

[mcanouil]

Brackets is for "code cell" meaning computation.
No brackets or dot languages are code blocks with syntax highlighting thus no computation.

[hguturu]

Ok. Thanks then I can focus on just {python} for formatting since presumably the other content is being used as text documentation with syntax highlighting.

[mcanouil]

It really feels you are doing the same thing as this extension: https://github.com/shafayetShafee/black-formatter

[hguturu]

The extension looks like it does the formatting at HTML render time, but I would like to have the source notebooks properly formatted for version control purposes (e.g. no diffs due to white space changes) and for linting PRs. Additionally, adding it to nbqa automatically allows support for other tools besides black. Specifically, I am interested in ruff and mypy since that is what is used for all our other python code for both pre-commit hooks and github branch protections.

It would also be nice if a _extensions directory didn't have to be committed with every project.