doc: comprehensive rename configuration guide with examples

[mcepl]

• Add detailed JSON configuration example for enabling pylsp-rope rename
• Clarify differences between rename plugins (pylsp_rope vs rope_rename vs jedi_rename)
• Include verification steps and current limitations
• Add comprehensive test suite demonstrating configuration patterns
• Document future benefits of using pylsp-rope's rename functionality

Fixes: #29

[lieryan]

I don't think we need to build the docs in GitHub Actions. RTD can build the docs with just build instructions in .readthedocs.yaml, which is what the rope repository did.

If we do have some legitimate reason to build docs here, the same reason probably applies to the rope repository as well.

[lieryan]

I don't think this directory exists?

[lieryan]

AFAICT, configurationSources is python-lsp-server setting which has nothing to do with pylsp-rope, so mentioning it in our docs doesn't really make much sense and is distraction.

[lieryan]

I don't use emacs, so can't test, but the example config here looks suspicious. Is this really how Emacs LSP work with the LSP config key names?

[lieryan]

This editor specific configuration here seems to overlap with the Rope Wiki. We should avoid duplicate documentations as that'll make it harder to maintain the docs, so either everything should go there, or everything should go here.

I kinda prefer these editor-specific docs to be documented in the Wiki since they are publicly editable, which make it easier for people outside the rope org to edit them. But as long as there's one place to document them, then it should be fine.

[mcepl]

On Wed Dec 31, 2025 at 6:15 PM CET, Lie Ryan wrote: @lieryan commented on this pull request. This editor specific configuration here seems to overlap with the [Rope Wiki](https://github.com/python-rope/rope/wiki/Rope-in-Vim-or-Neovim#lsp-setup). We should avoid duplicate documentations as that'll make it harder to maintain the docs, so either everything should go there, or everything should go here.

Yes, that’s true. And both of these are all duplicated in some part with the documentation for python-lsp-server (which is even bigger mess than what we have, I am afraid, in randomly spread Markdown files in https://github.com/python-lsp/python-lsp-server/ repository). It relates to problem what we believe is the main users’ entry point to whole system. I would think that 'python-rope/rope' is the lowest level library somewhere in the bottom, which no user should really know about, and it should be just pulled in by some kind of dependency management. The main entry point should be 'python-lsp-server', but because we don’t have its documentation under our control, then I guess we should concentrate all documentation in this repository, which is where users touch 'python-rope' universe first. Does it make sense?

I kinda prefer these editor-specific docs to be documented in the Wiki since they are publicly editable, which make it easier for people outside the rope org to edit them.

Well, https://github.com/openSUSE-Python/pylsp-rope/blob/rename_doc/doc/configuration.md has edit button as well (that small pencil icon), and I kind of prefer possibility of users to have documentation offline. I am also paranoid, so I prefer to have documentation not locked in the Microsoft proprietary format … could I download GitHub wiki and edit it offline, could I move it to some other host, if we decide, and I don’t vote for it now, to Codeberg, for example? Hmm, you can, https://docs.github.com/en/communities/documenting-your-project-with-wikis/adding-or-editing-wiki-pages#adding-or-editing-wiki-pages-locally I guess it is not that critical.

[mcepl]

On Wed Dec 31, 2025 at 6:03 PM CET, Lie Ryan wrote: @lieryan commented on this pull request. I don't use emacs, so can't test, …

Me neither, I just copied it from the old README.md.

[mcepl]

On Wed Dec 31, 2025 at 5:58 PM CET, Lie Ryan wrote: @lieryan commented on this pull request. +For VS Code with the Python LSP plugin, add to your `settings.json`: + +```json +{ + "pylsp.configurationSources": ["pycodestyle"], + "pylsp.plugins.pylsp_rope.enabled": true, + "pylsp.plugins.pylsp_rope.rename": true, + "pylsp.plugins.rope_rename.enabled": false, + "pylsp.plugins.jedi_rename.enabled": false +}

Actually, `rope_rename` is gone since python-lsp-server 1.11.0. Removed in c836c38.

[mcepl]

On Wed Dec 31, 2025 at 5:53 PM CET, Lie Ryan wrote: + "pylsp.configurationSources": ["pycodestyle"], AFAICT, this is python-lsp-server setting which has nothing to do with pylsp-rope, so mentioning it in our docs doesn't really make much sense and is distraction.

Besides, `["pycodestyle"]` is default these days, isn’t it?

[mcepl]

On Wed Dec 31, 2025 at 5:49 PM CET, Lie Ryan wrote: I don't think this directory exists?

Removed