Add docs for Ruff language server

[dhruvmanila]

Summary

This PR adds documentation for the Ruff language server.

It mainly does the following:

1. Combines various READMEs containing instructions for different editor setup in their respective section on the online docs
2. Provide an enumerated list of server settings. Additionally, it also provides a section for VS Code specific options.
3. Adds a "Features" section which enumerates all the current capabilities of the native server

For (2), the settings documentation is done manually but a future improvement (easier after ruff-lsp is deprecated) is to move the docs in to Rust struct and generate the documentation from the code itself. And, the VS Code extension specific options can be generated by diffing against the package.json in ruff-vscode repository.

Structure

1. Setup: This section contains the configuration for setting up the language server for different editors
2. Features: This section contains a list of capabilities provided by the server along with short GIF to showcase it
3. Settings: This section contains an enumerated list of settings in a similar format to the one for the linter / formatter
4. Migrating from ruff-lsp

Note

The settings page is manually written but could possibly be auto-generated via a macro similar to OptionsMetadata on the ClientSettings struct

resolves: #11217

Test Plan

Generate and open the documentation locally using:

1. python scripts/generate_mkdocs.py
2. mkdocs serve -f mkdocs.insiders.yml

[github-actions]

ruff-ecosystem results

Linter (stable)

✅ ecosystem check detected no linter changes.

Linter (preview)

✅ ecosystem check detected no linter changes.

Formatter (stable)

ℹ️ ecosystem check encountered format errors. (no format changes; 1 project error)

openai/openai-cookbook (error)

warning: Detected debug build without --no-cache.
error: Failed to parse examples/chatgpt/gpt_actions_library/gpt_action_outlook.ipynb:13:1:1: Expected an expression

Formatter (preview)

ℹ️ ecosystem check encountered format errors. (no format changes; 1 project error)

openai/openai-cookbook (error)

ruff format --preview

warning: Detected debug build without --no-cache.
error: Failed to parse examples/chatgpt/gpt_actions_library/gpt_action_outlook.ipynb:13:1:1: Expected an expression

[MichaReiser]

Thanks for putting the entire documentation together. It's very pretty and I like the overall structure.

I haven't read through the original PR, so it's likely that some of what I bring up here has been discussed on that PR.

My first impression is that we shouldn't set ruff server in the spotlight. The server is an implementation detail. What people are looking for is how they can use Ruff in their editor. The beauty of the server is that most VS code users will unlikely ever know that they use ruff server. It just works for them.

I don't think the documentation has to change significantly. It's just the structure that needs to change a little. I suggest renaming the top-level Ruff Server navigation entry to Editors, similar to Prettier, and change Integrations only to cover what's Other integrations today.

I think this will also help to reduce some overlap between Integrations and Ruff Server today where both cover the server and Ruff LSP.

This raises a few questions.

• What should we do with python-lsp-server and python-lsp-ruff. I'm leaning toward not mentioning them anymore. Or are there any workflows that these LSPs support that we don't?
• The main unclear thing is how we document the unofficially supported editors. But maybe that becomes a sub-section at the very end in editors?

A small side note. Why is the ruff server section expandable and the other sections aren't?

[dhruvmanila]

My first impression is that we shouldn't set ruff server in the spotlight. The server is an implementation detail. What people are looking for is how they can use Ruff in their editor. The beauty of the server is that most VS code users will unlikely ever know that they use ruff server. It just works for them.

I see what you mean. I like that way of framing Ruff's editor integration.

I don't think the documentation has to change significantly. It's just the structure that needs to change a little. I suggest renaming the top-level Ruff Server navigation entry to Editors, similar to Prettier, and change Integrations only to cover what's Other integrations today.

I think this will also help to reduce some overlap between Integrations and Ruff Server today where both cover the server and Ruff LSP.

I'm assuming that integrations using the ruff CLI would be moved in the specific editor setup section? For example, there are various plugins which can also be used for Neo(Vim) editor via ruff CLI as seen at the end.

• What should we do with python-lsp-server and python-lsp-ruff. I'm leaning toward not mentioning them anymore. Or are there any workflows that these LSPs support that we don't?

I think it might be ok to remove python-lsp-ruff. The only difference between workflows I see based on the README is custom severities and providing more configuration options directly in the server settings instead of pyproject.toml.

• The main unclear thing is how we document the unofficially supported editors. But maybe that becomes a sub-section at the very end in editors?

By this, I'm assuming you mean editors like PyCharm and Textmate. If so, then I think it should just be included in the "Editors" section given the rename. It wasn't included alongside other editors because the "The Ruff Language Server > Setup" section was specific to setting up the language server in those editors.

A small side note. Why is the ruff server section expandable and the other sections aren't?

It's because each section is in it's own file, otherwise the entire page becomes too cluttered with a lot of information. This is inspired by the uv docs. Internal message thread: https://discord.com/channels/1039017663004942429/1080996377611489350/1262939217437261907

[dhruvmanila]

Thinking about it a bit more...

Overall, there are two ways one could setup Ruff in their editor (except for VS Code where we provide an official extension):

1. Setting up the language server via some mechanism
2. Using the executable directly via some builtin mechanism or an external plugin

If there's just an "Editors" section, then we could include all different ways to setup Ruff in individual editors. But then I'm not sure if other sections (features, settings, etc.) goes under "Editors" because those sections are specific to the language server.

[MichaReiser]

I tried to find other projects that document their editors along with the tool itself and couldn't find any good examples.

If there's just an "Editors" section, then we could include all different ways to setup Ruff in individual editors. But then I'm not sure if other sections (features, settings, etc.) goes under "Editors" because those sections are specific to the language server.

I think the features section fits well because it's the features you (might) get when using Ruff in your editor. Assuming the editor supports the required LSP features.

I agree, that the settings are a bit more LSP specific. But I think we have a VS code setting for every LSP setting? We could even discuss the Common settings, followed by the editor specific settings.

[dhruvmanila]

@MichaReiser I've updated the structure and changed some wording as well. I might need to read through it once to update the "Ruff Language Server" references. What do you think of the new structure?

[tartley]

Thank you for this PR, this is amazing, perfect for me.