Document supported settings for ruff server

[snowsignal]

Right now, we don't have any centralized documentation for ruff server's client settings, similar to what ruff-lsp has in its README. This would be a useful resource for users to have, especially for clients that require settings to be added manually in configuration.

[charliermarsh]

Some of this in: astral-sh/ruff-vscode#469

[tartley]

Apologies for the uninformed drive-by, but as a user, I perceive the problem to be addressed here as two-fold:

1. As far as I can tell, the only current documentation of the available settings is in two places:

   1. The incidental mention on the ruff-lsp migration guide. I do not know if this list is exhaustive, but my uninformed browsing of the source makes me think it is.
   2. I see there have been recent merges which have refined a table of the available options on the ruff-vscode project README - but this is a bad place for it, people configuring other editors need this table too.

   This list should exist in somewhere more findable, more centrally applicable to all users of ruff server, not just those who are migrating from ruff-lsp or using VSCode.

2. For each of the editor specific guides, there needs to be an example which demonstrates how to provide the above settings in the initial lsp .setup() call (if that is actually the intent, I currently cannot tell.) For example, I'm looking at the Neovim setup guide, which:

   1. Links to nvim-lspconfig's #suggested-configuration, but this anchor does not exist in the linked document, nor does any similar-sounding title.

   2. Documents making the require('lspconfig').ruff.setup {} call without any args, which is fine.

   3. Links to the #ruff entry in the nvim-lspserver project. This documents the default values to the setup() call to be (cmd, filetypes, root_dir, settings, single_file_support). I infer that the 'settings' table is where I should pass the settings documented in the ruff-lsp/ruff-vscode projects above. However, I have been unable to get any of those settings to work here. Do I pass them as:

      require('lspconfig').ruff.setup{ settings={ lineLength=100 } }
      

      I cannot get this to work, having tried many variations on it. But the following does work for me:

      require('lspconfig').ruff.setup{ settings={ args={ "--line-length=100" } } }
      

      even though "args" is not documented on the above linked pages, not on the linked nvim-lspconfig entry, nor in the table of ruff server settings. Clearly I am misunderstanding. The docs should make this very clear.

I would send PRs, but I have no idea what I'm doing so wanted to at least chat about it first.

[dhruvmanila]

Hey @tartley, thank you for providing such a detailed analysis and sorry that you're facing this problem. @snowsignal can provide more details around it but I think the documentation for the new ruff server is in flux but we do plan to accumulate it in a central place like a "The Ruff Server" section at https://docs.astral.sh/.

I'll address a couple of points that you've mentioned here:

2. I see there have been recent merges which have refined a table of the available options on the ruff-vscode project README - but this is a bad place for it, people configuring other editors need this table too.

I think the settings provided in the linked table is specific to VS Code. Other editors need to configure it via other methods like setup function in Neovim and language.toml file for Helix. I think the goal of this issue is to address this need.

This list should exist in somewhere more findable, more centrally applicable to all users of ruff server, not just those who are migrating from ruff-lsp or using VSCode.

• For each of the editor specific guides, there needs to be an example which demonstrates how to provide the above settings in the initial lsp .setup() call (if that is actually the intent, I currently cannot tell.)

Yes, I completely agree with this.

1. Links to nvim-lspconfig's #suggested-configuration, but this anchor does not exist in the linked document, nor does any similar-sounding title.

Hmm, let me fix that quickly. I don't think nvim-lspconfig now provides any suggestion on the configuration as it did earlier. I think I'll just provide a minimal config or link to some :help topic.

3. Links to the #ruff entry in the nvim-lspserver project. This documents the default values to the setup() call to be (cmd, filetypes, root_dir, settings, single_file_support). I infer that the 'settings' table is where I should pass the settings documented in the ruff-lsp/ruff-vscode projects above. However, I have been unable to get any of those settings to work here. Do I pass them as:

   require('lspconfig').ruff.setup{ settings={ lineLength=100 } }
   

   I cannot get this to work, having tried many variations on it. But the following does work for me:

   require('lspconfig').ruff.setup{ settings={ args={ "--line-length=100" } } }
   

   even though "args" is not documented on the above linked pages, not on the linked nvim-lspconfig entry, nor in the table of ruff server settings. Clearly I am misunderstanding. The docs should make this very clear.

I'm sorry that you had to face this but the solution to this is to provide it under init_options. So, your example would be:

require('lspconfig').ruff.setup {
  init_options = {
    settings = {
      -- Ruff server settings would go here
    }
  }
}

I know this isn't obvious and we're going to fix this in #11897 and I'll add an example section in NEOVIM.md file as well.

[tartley]

@dhruvmanila Thank you for the detailed response! No apologies are necessary - my intent was not to complain, merely to try and help by being as explicit as I could about what I would like to see. Many thanks for all the amazing and exciting work to date, and to come!

[minusf]

it seems that over time lspconfig maintainers moved away from a suggested-configuration and provide only a "minimal" configuration for bug reporting. I am sure they have their reasons but it makes it much harder to pick up the package for people like me. Also some of those handed down mappings have became hardcoded defaults in neovim 0.10+.

I have been playing the dictionary hunting game for finding where a setting is picked up, where it isn't for ages and it's very frustrating. I wish docs writers would stop using "..." and actually used an actual argument in their examples.

For example it took me a lot of trying to find out how to overwrite the default cmd for ruff server... Is it in init_options? no. Is it in settings? no. Is it in settings inside init_options? no.

lspconfig.ruff.setup {
  cmd = { "ruff", "server", "--preview", "--config", "~/Library/Application Support/ruff/pyproject.toml"},
}

My use case to override a project specified pyproject.toml file with my own as it has more checks than the ones the team agreed on...

While I can confirm with LspInfo that the command arguments are picked up, ruff still seems to favour the closest pyproject.toml file in the project directory, so now I am confused about the documentation: https://docs.astral.sh/ruff/configuration/#config-file-discovery point no 2...

Client: ruff (id: 2, bufnr: [1])
      filetypes:       python
      autostart:       true
 root directory:       ...
            cmd:       /opt/homebrew/bin/ruff server --preview --config ~/Library/Application Support/ruff/pyproject.toml

The new diagnostics show up only if I remove the project's pyproject.toml file. AAAnyway, I digressed a bit :D

[minusf]

ah, turning on the trace messages told me at least to move the config file to .config.

[minusf]

to give a positive update to my issue for anyone looking at a similar problem, ruff-lsp has honoured the settings correctly:

require('lspconfig').ruff_lsp.setup {
  init_options = {
    settings = {
      -- Any extra CLI arguments for `ruff` go here.
      args = {"--config", "~/.config/ruff/pyproject.toml"},
    }
  }
}

so back to ruff-lsp for a little while.

[dhruvmanila]

@minusf Sorry that you're facing this, I agree that it's very frustrating to find where a specific information goes with the amount of options available. I'm going to be working on the new ruff server documentation next week and this is helpful context to guide in how I should go about writing the examples. Thank you for sharing this.

[minusf]

To be clear, I think this is an lspconfig issue first, other projects later. They just kind of expect everyone to be a lua dev 🤣

[dhruvmanila]

Thank you all for providing feedback here! It was helpful while writing the documentation. Feel free to provide any additional suggestions that you might have in the new documentation. Reference: https://docs.astral.sh/ruff/editors

[tartley]

Yes, I've been poring through it right now. I'll let you know and could work on modest PRs if I spot anything.

…

On Thu, Jul 18, 2024, at 12:36, Dhruv Manilawala wrote: Thank you all for providing feedback here! It was helpful while writing the documentation. Feel free to provide any additional suggestions that you might have in the new documentation. Reference: https://docs.astral.sh/ruff/editors — Reply to this email directly, view it on GitHub <#11217 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABBV66D3YMTUCDIME7GBR3ZNADJVAVCNFSM6AAAAABHAVNULKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEMZXGI2DONBUGU>. You are receiving this because you were mentioned.Message ID: ***@***.***>

-- Jonathan Hartley USA, Central(UTC-5) ***@***.*** https://tartley.com