Skip to content

Commit

Permalink
Update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@InSyncWithFoo
InSyncWithFoo committed Sep 7, 2024
1 parent 0cb7e21 commit d8d0bf7
Show file tree
Hide file tree
Showing 11 changed files with 268 additions and 161 deletions.
2 changes: 1 addition & 1 deletion build.gradle.kts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -144,7 +144,7 @@ tasks {
systemProperty("ide.browser.jcef.headless.enabled", "true")
systemProperty("ide.tree.painter.compact.default", "true")
systemProperty("projectView.hide.dot.idea", "false")
systemProperty("terminal.new.ui", "false")
systemProperty("terminal.new.ui", "true")
}

wrapper {
Expand Down
Binary file modified docs/assets/uv-new-project-panel.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
195 changes: 96 additions & 99 deletions docs/configurations/ruff.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,9 @@ to find one in the following order:

## Cross-platform executable resolution

If this option is enabled, the executable will be resolved against
the project's interpreter directory, with its extension removed.
If this option is enabled and the executable is specified
as a relative path, it will be resolved against the project's
interpreter directory with its extension removed.

This is useful if Ruff is a development dependency
and is expected to always be installed,
Expand All @@ -30,183 +31,168 @@ and the [`configuration`][1] language server setting.

## Running mode

The manner in which [linting diagnostics][2] are provided.
The manner in which the executable is invoked.

Default: <i>Command line</i>

!!! info "See <i>[Running modes][2]</i> for more information."

## Tooltips

## Main functionalities

### Tooltip format

The format in which tooltips are displayed.
### Linting

Default: <i>A123: Message</i>
Whether [linting errors][3] (diagnostics) should be shown.

=== "Message"
![](../assets/configurations-ruff-tooltip-format-demo-message.png)
This corresponds to the [`lint.enable`][4] language server setting.

=== "A123: Message"
![](../assets/configurations-ruff-tooltip-format-demo-rule-message.png)
Default: `true`

=== "Ruff (A123): Message"
![](../assets/configurations-ruff-tooltip-format-demo-ruff-rule-message.png)
!!! info "See <i>[Linting][5]</i> for more information."

=== "Message Ruff(A123)"
![](../assets/configurations-ruff-tooltip-format-demo-message-ruff-rule.png)

#### Report syntax errors

## Formatting
Whether diagnostics for syntax errors should be shown.

Settings in this group controls [the events][3]
on which Ruff's formatter is triggered.
This corresponds to the [`showSyntaxErrors`][6] language server setting.

Default: `false`

### On save

Whether files should be formatted by Ruff before saving.
#### Tooltip format

Default: `true`
The format in which tooltips are displayed.

Default: <i>A123: Message</i>

### On save, but only project files
=== "Message"
![](../assets/configurations-ruff-tooltip-format-demo-message.png)

Whether only files belong to the current project should be formatted by Ruff.
=== "A123: Message"
![](../assets/configurations-ruff-tooltip-format-demo-rule-message.png)

Default: `true`
=== "Ruff (A123): Message"
![](../assets/configurations-ruff-tooltip-format-demo-ruff-rule-message.png)

=== "Message Ruff(A123)"
![](../assets/configurations-ruff-tooltip-format-demo-message-ruff-rule.png)

### On reformat

Whether the <i>Reformat Code</i> action should trigger Ruff.
### Quick fixes

Whether [quick fixes][7] (code actions) should be suggested.

Default: `true`


### On optimize imports
#### Fix all fixable violations

Whether the <i>Optimize Imports</i> action should trigger Ruff.

Default: `true`
Whether a quick fix to fix all safely fixable violations should be suggested.

This corresponds to the [`fixAll`][8] language server setting.

## Documentation
Default: `true`

This group controls the behaviour of [documentation popups][4].

#### Organize imports

### For `noqa` codes
Whether a quick fix to organize the imports section should be suggested.

Whether documentation popups should be shown when
<code>noqa</code> codes in Python comments are hovered.
This corresponds to the [`organizeImports`][9] language server setting.

Default: `true`


### For TOML keys

Whether documentation popups should be shown when
the keys of the `tool.ruff` table in the `pyproject.toml` file
(or top-level keys for `ruff.toml`/`.ruff.toml`) are hovered.
#### Disable rule for line

Default: `true`
Whether a quick fix to disable a given rule
for the current line should be suggested.

This corresponds to the [`codeAction.disableRuleComment.enable`][10]
language server setting.

## Language server settings
Default: `true`

Some of these settings' values are passed to Ruff as
language server [initialization options][5].

#### Fix single violation

### Automatically restart servers on configuration change
Whether a quick fix specific to the current violation should be suggested.

Whether the running servers should be restarted immediately
when the <i>Apply</i>/<i>OK</i> buttons are clicked.
This corresponds to the [`codeAction.fixViolation.enable`][11]
language server setting.

Default: `true`


### Hover support
### Formatting

Whether the language server's [hover support][6] should be used.
Whether [Ruff's formatter][12] should be used
instead of the IDE's default formatter.

Default: `true`

!!! info "See <i>[Formatting][13]</i> for more information."

### Formatting support

Whether the language server's [formatting support][7] should be used.
#### Run on reformat

Whether the <i>Reformat Code</i> action should trigger Ruff.

Default: `true`


### Diagnostics support
#### Run on optimize imports

Whether the language server's [linting support][8] should be used.
Whether the <i>Optimize Imports</i> action should trigger Ruff.

Default: `true`


### Show diagnostics for syntax errors
#### Run on save

Whether syntax error diagnostics should be shown.

This corresponds to the [`showSyntaxErrors`][9] language server setting.
Whether files should be formatted by Ruff before saving.

Default: `false`


### Code actions support

Whether the language server's [quick fix support][10] should be used.

Default: `true`
##### Project files only


### Fix all problems in one action

Whether the [`source.fixAll`][11] code action should be used.

This corresponds to the [`fixAll`][12] language server setting.
Whether only files belong to the current project should be formatted by Ruff.

Default: `true`


### Organize imports
### Documentation popups

Whether the [`source.organizeImports`][11] code action should be used.

This corresponds to the [`organizeImports`][13] language server setting.
Whether [documentation popups][14] should be shown.

Default: `true`

!!! info "See <i>[Documentation][15]</i> for more information."

### Suppress rules

Whether the code action to suppress a problem should be used.
#### For rule codes in `noqa` comments

This corresponds to the [`codeAction.disableRuleComment.enable`][14]
language server setting.
Whether documentation popups should be shown when
<code>noqa</code> codes in Python comments are hovered.

Default: `true`


### Fix problems

Whether the code action corresponding to
the quick fix for a problem should be used.
#### For TOML keys

This corresponds to the [`codeAction.fixViolation.enable`][15]
language server setting.
Whether documentation popups should be shown when
the keys of the `tool.ruff` table in the `pyproject.toml` file
(or top-level keys for `ruff.toml`/`.ruff.toml`) are hovered.

Default: `true`


### Log level

Controls the amount of logs
the language server will emit.
The amount of logs the language server will emit.

This corresponds to the [`logLevel`][16] language server setting.

Expand All @@ -229,7 +215,7 @@ Whether RyeCharm should automatically find a potential
Ruff executable and suggest setting that as the executable
for the current project on some events.

See also [the corresponding action][18].
This feature can also be [triggered as an action][18].


#### On project open
Expand All @@ -244,24 +230,35 @@ Default: `true`
Whether a potential executable should be suggested when
a package is installed via the <i>Python Packages</i> toolwindow.

Default: `true`


## Advanced settings


### Automatically restart servers on configuration change

Whether the running servers should be restarted immediately
when the <i>Apply</i>/<i>OK</i> buttons are clicked.

Default: `true`


[1]: https://docs.astral.sh/ruff/editors/settings/#configuration
[2]: ../ruff/linting.md
[3]: ../ruff/formatting.md
[4]: ../ruff/documentation.md
[5]: https://docs.astral.sh/ruff/editors/settings/
[6]: https://docs.astral.sh/ruff/editors/features/#hover
[7]: https://docs.astral.sh/ruff/editors/features/#formatting
[8]: https://docs.astral.sh/ruff/editors/features/#diagnostic-highlighting
[9]: https://docs.astral.sh/ruff/editors/settings/#showsyntaxerrors
[10]: https://docs.astral.sh/ruff/editors/features/#code-actions
[11]: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_codeAction
[12]: https://docs.astral.sh/ruff/editors/settings/#fixall
[13]: https://docs.astral.sh/ruff/editors/settings/#organizeimports
[14]: https://docs.astral.sh/ruff/editors/settings/#disablerulecommentenable
[15]: https://docs.astral.sh/ruff/editors/settings/#fixviolationenable
[2]: ../ruff/running-modes.md
[3]: https://docs.astral.sh/ruff/editors/features/#diagnostic-highlighting
[4]: https://docs.astral.sh/ruff/editors/settings/#lint_enable
[5]: ../ruff/linting.md
[6]: https://docs.astral.sh/ruff/editors/settings/#showsyntaxerrors
[7]: https://docs.astral.sh/ruff/editors/features/#code-actions
[8]: https://docs.astral.sh/ruff/editors/settings/#fixall
[9]: https://docs.astral.sh/ruff/editors/settings/#organizeimports
[10]: https://docs.astral.sh/ruff/editors/settings/#disablerulecommentenable
[11]: https://docs.astral.sh/ruff/editors/settings/#fixviolationenable
[12]: https://docs.astral.sh/ruff/editors/features/#formatting
[13]: ../ruff/formatting.md
[14]: https://docs.astral.sh/ruff/editors/features/#hover
[15]: ../ruff/documentation.md
[16]: https://docs.astral.sh/ruff/editors/settings/#loglevel
[17]: https://docs.astral.sh/ruff/editors/settings/#logfile
[18]: ../ruff/actions.md#suggest-project-executable
39 changes: 19 additions & 20 deletions docs/ruff/formatting.md
View file
Original file line number Diff line number Diff line change
@@ -1,40 +1,39 @@
RyeCharm can trigger Ruff to format a file on three events:

* File save (<kbd>Ctrl</kbd> + <kbd>S</kbd>, editor close, IDE close, etc.)
* Reformat (<kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>L</kbd> or similar)
* Optimize imports (<kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>O</kbd> or similar)
* Reformat (<kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>L</kbd>)
* Optimize imports (<kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>O</kbd>)
* File save (<kbd>Ctrl</kbd> + <kbd>S</kbd>, editor tab close, IDE close, etc.)

Unsupported files are not affected.


## File save

Everytime a file is [saved][1], automatically or manually,
RyeCharm will run Ruff on it if it is a supported file.

This is equivalent to running `ruff format --quiet` with the file as input.


## Reformat

This event happens when the [<i>Reformat Code</i>][2] action
(<kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>L</kbd> or similar)
This event happens when the [<i>Reformat Code</i>][1] action
(<kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>L</kbd>)
is triggered, possibly with some code selected.

This is equivalent to running `ruff format --quiet --range ...`
In <i>Command line</i> mode, this is equivalent to
running `ruff format --quiet --range ...`
with the file and the selected range as input.


## Optimize imports

This event happens when the [<i>Optimize Imports</i>][3] action
(<kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>O</kbd> or similar)
is triggered.
This event happens when the [<i>Optimize Imports</i>][2] action
(<kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>O</kbd>) is triggered.

This is equivalent to running `ruff check --fix --exit-zero --quiet --select I`
with the file as input.


[1]: https://www.jetbrains.com/help/pycharm/saving-and-reverting-changes.html
[2]: https://www.jetbrains.com/help/pycharm/reformat-and-rearrange-code.html
[3]: https://www.jetbrains.com/help/pycharm/creating-and-optimizing-imports.html#optimize-imports
## File save

This event happens when a file is [saved][3], automatically or manually.

This is equivalent to running `ruff format --quiet` with the file as input.


[1]: https://www.jetbrains.com/help/pycharm/reformat-and-rearrange-code.html
[2]: https://www.jetbrains.com/help/pycharm/creating-and-optimizing-imports.html#optimize-imports
[3]: https://www.jetbrains.com/help/pycharm/saving-and-reverting-changes.html
Loading

0 comments on commit d8d0bf7

Please sign in to comment.