Autoformatting Python code in docstrings

[martonvago]

Investigate if and how docstrings can be auto-formatted:

1. docstring examples
2. Python code in Quarto docs

[martonvago]

@lwjohnst86 @signekb Here's what I've found:

docstring examples:

• With docstring-code-format = true, ruff formats ```python blocks but not ```{python} blocks. Seems like Apply ruff formatting to markdown code blocks astral-sh/ruff#3792 would help with this?
• As an interim solution we could write a script like: (1) remove {} brackets, (2) format, (3) add back {} brackets
• There's blacken-docs for formatting Python code in docstrings with black, but this doesn't recognise ```{python} blocks either.

Python code in Quarto docs:

• We have "editor.formatOnSave": false in settings.json for qmd files. Without this, code blocks are actually formatted by whatever formatter the VSCode Quarto extension uses. But the formatting is not perfect (e.g. it changes x = 'x' to x = "x' at the end of a block). Presumably this is why it's disabled?
• There's a Quarto extension black-formatter for formatting Python code blocks. This needs black installed and the formatting only shows up in the rendered output.
• We could use the same bracket-swapping script on Quarto files, but then we need a formatter that supports qmd. E.g. blacken-docs instead of ruff.

[martonvago]

Based on what we discussed, I'll move this back to TODO pending the linked issue