Conversation
amyreese
requested review from
BurntSushi,
dylwil3 and
ntBre
and removed request for
BurntSushi
ntBre
left a comment
ntBre
left a comment
There was a problem hiding this comment.
Nice! Just a couple of small nits, and I think I might have learned a new Markdown link syntax 😆
Summary -- I noticed this while reviewing #22990 Test Plan --
docs/formatter.md
Outdated
| While in preview release, Ruff will not automatically find and format Markdown | ||
| files in your project, but will format any Markdown files directly passed as | ||
| an argument. To include Markdown files when running Ruff on your project, | ||
| add them with [`extend-include`](settings.md#extend-include) in your | ||
| project settings: |
There was a problem hiding this comment.
I think this could be reworded a bit.
First a nit: remove "While in preview release" since this is stated already at the beginning and end of this documentation.
But mainly: I think folks might not necessarily guess what happens if they do something like ruff format docs/ where docs/ has only Markdown files.
There was a problem hiding this comment.
I mostly put the "while in preview" part to imply that the behavior is likely to change once we stabilize the feature.
docs/formatter.md
Outdated
|
|
||
| ## Markdown code formatting | ||
|
|
||
| *Formatting for Markdown code blocks is currently only available in [preview mode](preview.md#preview).* |
There was a problem hiding this comment.
| *Formatting for Markdown code blocks is currently only available in [preview mode](preview.md#preview).* | |
| *Formatting for code blocks in Markdown files is currently only available in [preview mode](preview.md#preview).* |
docs/formatter.md
Outdated
|
|
||
| *Formatting for Markdown code blocks is currently only available in [preview mode](preview.md#preview).* | ||
|
|
||
| The Ruff formatter can also format Markdown files with a `.md` extension. |
There was a problem hiding this comment.
This is a little misleading, even though it is clarified in the next sentence, since it makes it seem like Ruff formats the whole markdown file, not just the Python code inside it.
Also I think the .md extension clause is unnecessary, though technically correct - in the same way that a Python file need not have a .py (etc.) ending, but that is how we discover them. We still just say "Python files". You could clarify later that they are discovered via the .md extension (and sort of do say that later on anyway).
| ```toml | ||
| [tool.ruff] | ||
| # Find and format code blocks in Markdown files | ||
| extend-include = ["*.md"] |
There was a problem hiding this comment.
Just to clarify, something like extend-include = ["docs/*.md"] also works as expected, but extend-include = ["docs/*"] does nothing?
There was a problem hiding this comment.
I think it's fine for this glob not to end with *.md, but I did have to check:
❯ ~/astral/worktrees/ruff1/target/debug/ruff format --check --no-cache --config 'extend-include=["*"]' --preview
unformatted: File would be reformatted
--> try.md:1:1
1 | ```py
- import math
2 + import math
3 | ```There was a problem hiding this comment.
The extension needs to be included, otherwise ruff will also discover other files that aren't python/markdown/toml, and will end up trying to format them as python:
$ ruff format --check --preview --config 'extend-include=["docs/*"]' docs/ | grep -C1 extra.js
invalid-syntax: Simple statements must be separated by newlines or semicolons
--> docs/js/extra.js:1:1
|
Reworded some bits to reduce repetition, moved the mention of |
Summary -- I noticed this while reviewing #22990. I'm not really sure why the current version doesn't work, but the new one definitely does. Test Plan -- [Before](https://docs.astral.sh/ruff/formatter/#docstring-formatting): <img width="457" height="77" alt="image" src="https://github.com/user-attachments/assets/3d4394b7-eadf-41ec-81c9-cea6190fa0bb" /> After: <img width="493" height="84" alt="image" src="https://github.com/user-attachments/assets/66f0700c-9312-40b9-b3ae-11edcaec7562" />
4 participants
No description provided.