Provide links to locally built documentation for experimental/externalDocs

[Ddystopia]

This pull request addresses issue #12867, which requested the ability to provide links to locally built documentation when using the "Open docs for symbol" feature. Previously, rust-analyzer always used docs.rs for this purpose. With these changes, the feature will provide both web (docs.rs) and local documentation links without verifying their existence.

Changes in this PR:

• Added support for local documentation links alongside web documentation links.
• Added target_dir path argument for external_docs and other related methods.
• Added sysroot argument for external_docs.
• Added target_directory path to CargoWorkspace.

API Changes:

• Added an experimental client capability { "localDocs": boolean }. If this capability is set, the Open External Documentation request returned from the server will include both web and local documentation links in the ExternalDocsResponse object.

Here's the ExternalDocsResponse interface:

interface ExternalDocsResponse {
    web?: string;
    local?: string;
}

By providing links to both web-based and locally built documentation, this update improves the developer experience for those using different versions of crates, git dependencies, or local crates not available on docs.rs. Rust-analyzer will now provide both web (docs.rs) and local documentation links, leaving it to the client to open the desired link. Please note that this update does not perform any checks to ensure the validity of the provided links.

[nemethf]

Can this be implemented in a backward compatible way? I.e., clients conforming to the current extension might fail in the future because the type of the return value has changed. (One possibility to overcome this issue is make rust-analyzer check for a client capability like, for example, "externalDocs": {"version": 2}.)

Also, does the local documentation count as "external documentation"?

Thank you.

[Ddystopia]

Can this be implemented in a backward compatible way? I.e., clients conforming to the current extension might fail in the future because the type of the return value has changed. (One possibility to overcome this issue is make rust-analyzer check for a client capability like, for example, "externalDocs": {"version": 2}.)

As far as I know, rust-analyzer does not provide a stable API interface, so breakage is fine.
Also, there is #4604 for this purpose. As stated:

This issue exists to announce changes which might affect rust-analyzer plugins for different editors.
If you maintain such a plugin, consider subscribing to this issue.

Also, does the local documentation count as "external documentation"?

I assume that "external documentation" is documentation outside of the editor.

Maybe, it would be better to create something like experimental/localDocs?

Thank you for your comment.

[nemethf]

As far as I know, rust-analyzer does not provide a stable API interface, so breakage is fine. Also, there is #4604 for this purpose. As stated:

This issue exists to announce changes which might affect rust-analyzer plugins for different editors.
If you maintain such a plugin, consider subscribing to this issue.

Maybe you're right. But to me, this text only says how plugin-maintainers can keep up with the changes of the lsp-extensions and says nothing about a possible breakage.

Also, does the local documentation count as "external documentation"?

I assume that "external documentation" is documentation outside of the editor.

Maybe, it would be better to create something like experimental/localDocs?

I don't know, but I start to wonder why it is necessary to introduce protocol extensions for this feature. The LSP client can send a standard compliant workspace/executeCommand request and the server can send a window/showDocument request right after receiving the executeCommand. The name of the command and its arguments and return value still need to be documented, though.

[bors]

☔ The latest upstream changes (presumably #14664) made this pull request unmergeable. Please resolve the merge conflicts.

[bors]

☔ The latest upstream changes (presumably #11557) made this pull request unmergeable. Please resolve the merge conflicts.

[Veykril]

two nits, otherwise lgtm, thanks!
@bors delegate+

[bors]

✌️ @Ddystopia can now approve this pull request

[Veykril]

I don't know, but I start to wonder why it is necessary to introduce protocol extensions for this feature. The LSP client can send a standard compliant workspace/executeCommand request and the server can send a window/showDocument request right after receiving the executeCommand. The name of the command and its arguments and return value still need to be documented, though.

How is using workspace/executeCommand any different? The client still needs to know about the command there that the server supports. And the server replying with window/showDocument would limit in what the client can do, the can't decide to open things in a browser if it wants to for example.

[Ddystopia]

@bors r+

[bors]

📌 Commit 2025f17 has been approved by Ddystopia

It is now in the queue for this repository.

[bors]

⌛ Testing commit 2025f17 with merge c9b4116...

[bors]

☀️ Test successful - checks-actions
Approved by: Ddystopia
Pushing c9b4116 to master...

[nemethf]

I don't know, but I start to wonder why it is necessary to introduce protocol extensions for this feature. The LSP client can send a standard compliant workspace/executeCommand request and the server can send a window/showDocument request right after receiving the executeCommand. The name of the command and its arguments and return value still need to be documented, though.

How is using workspace/executeCommand any different? The client still needs to know about the command there that the server supports. And the server replying with window/showDocument would limit in what the client can do, the can't decide to open things in a browser if it wants to for example.

As the showDocument request supports an "external" flag, the server can implement the logic of determining how the client should open the documentation. This way the client-side code can be smaller, which is a desirable goal, I think.

At any rate, I'm happy with the merged feature. Thanks @Ddystopia and @Veykril!