Document how to actually use the server with an editor

[ZayanKhan-12]

Description

Refs #194.

This does not publish a VS Code extension, and is not a fix for #194 as titled. @ccordoba12 already answered that in 2020 — "we don't have plans to create a VSCode extension for this server because most contributors use it for other editors and IDEs" — and that is not a contributor's call to overturn.

What the thread does contain is a request that was never answered. @munael, right after that reply:

Can we add some documentation on enabling it for some IDEs? I assumed that installing the pip package would somehow register it for vscode to catch, but that doesn't seem to be the case.

and @Stercator in 2022:

there's so little support on actually using it... without an actual integration, it stays just a dream

They are right that the docs do not cover this. The README explains how to pip install the package, and has a "Develop against VS Code" section for developing the server, but nothing anywhere says how a user connects it to an editor. #834, "Unable to run pyls with VS code", is still open.

Changes

A "Using the server with an editor" section covering:

• The package installs a pyls executable; clients launch it and talk over stdin/stdout.
• --tcp --host --port exists for clients that cannot spawn the process.
• pyls -v is the first thing to reach for when an editor reports no results.
• Which LSP clients people commonly use per editor (Vim/Neovim, Emacs, Sublime Text, Kate).
• That server settings like pyls.plugins.pydocstyle.enabled are sent by the client, so they live in the client's config — which is not obvious and is the shape of several existing issues.

I verified both invocations rather than transcribing them from the argument parser: pyls over stdio and pyls --tcp --port 8799 each complete an LSP initialize handshake and advertise the full capability set.

And a short Visual Studio Code subsection, placed where someone hunting for an extension will actually find it, recording that there is no official extension and no plans for one, linking your answer in #194. It also states plainly that vscode-client/ is not that extension — it is unpublished, it is version 0.0.1 under an inherited publisher, and its own README says it launches a separate VS Code instance because it conflicts with other Python extensions. Someone arriving at that directory expecting a usable extension currently has no way to know this.

The second commit is separate and independent. The pydocstyle example in the Configuration section is fenced with markdown backticks inside an .rst file, so docutils reports Possible title underline, too short for the title and renders the snippet as ordinary text. README.rst is the long_description in setup.py, so that affects the PyPI page too. I noticed it because I link to that section. With it fixed, README.rst parses with no warnings at all. Drop that commit if you would rather keep this PR to one thing.

Verification

• README.rst parses clean under docutils (no warnings, versus one before), and renders to HTML without error.
• setup.py still reads it as long_description.
• pytest test/: 12 failed, 99 passed, 8 skipped — identical to the baseline on develop, as expected for a docs-only change. Those 12 are pre-existing and track linter versions that moved on since 2020.
• pycodestyle clean, pyflakes unchanged (one pre-existing _utils.py warning).

Notes

I have deliberately not named a specific third-party VS Code extension. Recommending one by name in your README implies a level of endorsement and review I am not in a position to offer, and those extensions come and go; describing the mechanism seemed more honest and more durable. Happy to add one if you have a preference.

If you would rather close #194 outright given the 2020 answer, this section at least means the next person to ask finds the answer in the README instead of eight years of issue history.

CLAUDE.md lives in my other open PR (#982) and is not duplicated here.

[palantirtech]

Thanks for your interest in palantir/python-language-server, @ZayanKhan-12! Before we can accept your pull request, you need to sign our contributor license agreement - just visit https://cla.palantir.com/ and follow the instructions. Once you sign, I'll automatically update this pull request.