Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

x/tools/gopls: support for an IDE documentation viewer #55861

Open
firelizzard18 opened this issue Sep 25, 2022 · 11 comments
Open

x/tools/gopls: support for an IDE documentation viewer #55861

firelizzard18 opened this issue Sep 25, 2022 · 11 comments
Labels
FeatureRequest gopls Issues related to the Go language server, gopls. Tools This label describes issues relating to any tools in the x/tools repository.

Comments

@firelizzard18
Copy link
Contributor

I propose adding a documentation request/response to gopls. As a user, I want to easily view documentation for the code I'm working on, and ideally for private modules I am using. As a developer, I am interested in contributing a documentation viewer to the VSCode extension.

I've considered a number of possibilities for adding a documentation viewer to the extension. Fundamentally, any such solution must involve either parsing Go or go doc comments in JavaScript/TypeScript, or calling a separate binary. Not wanting to build a parser, I explored using godoc or gddo. Using a server model is annoying because the extension would need code to manage the lifetime of that server. On the other hand, calling a binary to parse a given file is less code but more overhead and either of the aforementioned tools are particularly suited to that - I spent a couple days exploring that.

I think an elegant solution would be to add a method to gopls that requests documentation for a given symbol or package:

  • gopls already has tooling for reading and parsing source
  • go/doc can be used to parse doc comments
  • When gopls is built with Go 1.19+, go/doc/comment can be used to provide richer output

I am interested in implementing this. Hopefully parsing doc comments for workspace files will be relatively simple. For other packages, I can leverage the fact that gopls already knows how to determine which version of a package is in use and knows how to locate that file in the module cache.

@gopherbot gopherbot added Tools This label describes issues relating to any tools in the x/tools repository. gopls Issues related to the Go language server, gopls. labels Sep 25, 2022
@gopherbot gopherbot added this to the Unreleased milestone Sep 25, 2022
@firelizzard18
Copy link
Contributor Author

@gopherbot, please remove label Documentation

This relates to documentation, but it is a task to write code, not to write documentation.

@firelizzard18
Copy link
Contributor Author

@gopherbot, please add label FeatureRequest

@hyangah
Copy link
Contributor

hyangah commented Sep 30, 2022

Thanks for filing the feature request.

We discussed this feature during our triage meeting.

I personally dreamed of this feature. But for long-term maintainability, we will need careful design, discussion, and code review.
Unfortunately, the gopls team does not have bandwidth for the needed support right now.

It looks like you were thinking to implement this as a custom gopls command. Gopls custom command is not too different from running a separate command except that the command can have access to the parsed go files already. However, that information should be also available with golang.org/x/tools/go/packages and go list too.

How about making this feature as a separate command & extension first?
Prototype & demo may help people see the value of this feature more clearly.

  • Another aspect to consider: if it is implemented using gopls custom commands, it's likely that only certain editors (e.g vscode) that can implement UI frontend will benefit from this feature. If it's implemented as a web server (maybe running on gopls?), other editor users may utilize the feature through web browsers.

@hyangah hyangah modified the milestones: Unreleased, gopls/unplanned Sep 30, 2022
@firelizzard18
Copy link
Contributor Author

Gopls custom command is not too different from running a separate command except that the command can have access to the parsed go files already.

In my view the main differences are that using gopls requires less additional code and gets the advantage of a long-running process that can cache work without the complexity of managing an additional process.

How about making this feature as a separate command & extension first?
Prototype & demo may help people see the value of this feature more clearly.

👍

Another aspect to consider: if it is implemented using gopls custom commands, it's likely that only certain editors (e.g vscode) that can implement UI frontend will benefit from this feature. If it's implemented as a web server (maybe running on gopls?), other editor users may utilize the feature through web browsers.

Taking HTML output from a tool and embedding it in a webview puts significant restrictions on integration with the IDE. I experimented with taking HTML output from gddo (or was it godoc?) and putting it in a webview. IMO that experience is not good. I feel the same about the pprof webviewer, but I am not going to write a custom profile viewer so it's good enough.

For documentation, I want the command to provide structured data about the package and I want it to be the extension's responsibility to convert that to a UI.

@Southclaws
Copy link

I've recently run into this as I wanted to provide a ton of documentation and examples with properly formatted text on pkg.go.dev but the existing godoc tool doesn't support all this formatting so it comes down to either trial and error pushing and waiting for go.dev to pick up the changes or try to run pkgsite locally (which isn't well documented and requires a ton of external dependencies like a database and message queue from what I can tell)

So I'd like to help on this, I'd love to see something like this land in the official vscode extension or some feature in gopls. Perhaps we could collaborate on a proof of concept?

@aarzilli
Copy link
Contributor

aarzilli commented Nov 1, 2022

the existing godoc tool doesn't support all this formatting

Support for the new formatting (links, lists and headings) was added to godoc in 79f3242e4b2ee6f1bd987fdd0538e16451f7523e

@Southclaws
Copy link

Oh I didn't know about that! I'm on quite an old version, thanks!

@adonovan
Copy link
Member

FWIW, the way I would like to address this feature is by adding a gopls command that would cause it to start a pkgsite instance on a local loopback port, and send a showDocument(http://localhost:12354/pkg/foo) request to the client (e.g. VSCode) which would then open a browser tab. Pkgsite would render the documentation for the workspace packages, including local edits (and eventually perhaps including unsaved local edits). The pkgsite links to the source code would link to endpoints within gopls that cause it to send showDocument(file:...) requests back to the client editor, so the net effect would be that you can seamlessly navigate between editor and pkgsite and back again just by clicking.

@firelizzard18
Copy link
Contributor Author

firelizzard18 commented Apr 10, 2023

@adonovan Is this something you're planning to work on or suggesting the core team do this, or are you speaking in a hypothetical sense? I was thinking of working on an extension as @hyangah suggested when I have time, but if the core team will be working on it I don't want to duplicate your efforts.

Running a pkgsite instance and opening a browser tab (within VSCode I assume?) would certainly be the simplest solution and I believe it could be done without any custom LSP methods. However I personally would like something more seamless as I discussed above. I'd like to have a side bar view for browsing packages/types/etc and I'd prefer the actual documentation display/tab to feel like it's a native part of VSCode as opposed to an embedded website. Thus my suggestion that gopls return a structured response that the extension can do what it wants with.

@adonovan
Copy link
Member

I plan on working on the feature I described, since it allows users to see the documentation exactly as it will appear in the production pkgsite service. I think it should be straightforward to implement.

Running a pkgsite instance and opening a browser tab (within VSCode I assume?)

When an editor (e.g. VSCode, Emacs) gets a showDocument request, it typically opens file: URLs as editor buffers, and http: URLs in the system browser, via open(1) or xdg(1). I think there's a way to request an embedded browser tab within the editor, but in my limited testing VSCode didn't seem to honor it.

I personally would like something more seamless as I discussed above. I'd like to have a side bar view for browsing packages/types/etc and I'd prefer the actual documentation display/tab to feel like it's a native part of VSCode as opposed to an embedded website. Thus my suggestion that gopls return a structured response that the extension can do what it wants with.

That sounds like it would require a Go- and VSCode-specific extension, which limits its usefulness to users of a single client editor. It also sounds like it might have significant functionality overlap with the existing Hover and Outline functionality. It may be a reasonable thing to do, but we should take care to avoid feature redundancy or significant extra complexity. It might be worth a quick prototype before you spend too long on it.

@hyangah may be in a better position to advise w.r.t. VSCode-specific features.

@firelizzard18
Copy link
Contributor Author

Ultimately I have two more or less independent desires:

  1. Preview what my documentation will look like on pkg.go.dev
  2. View documentation within my development environment

(1) is clearly served best by your solution, since it would literally be doing exactly that (rendering it exactly as pkg.go.dev will). My goal for (2) is to present similar or the same information as what I see on pkg.go.dev but in a way that is more seamless and interrupts my development flow less than switching to a browser. Hover and outline functionality are very useful, but often I want a more holistic view where I can browse through all the declarations made in a package. Ultimately pkg.go.dev provides all of that, but I'd prefer to have it right within my IDE. If and when I start working on this, I think I'll do it as an extension that calls out to an executable each time. That will be a lot less efficient than a long-running process but it will be a lot easier to implement.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
FeatureRequest gopls Issues related to the Go language server, gopls. Tools This label describes issues relating to any tools in the x/tools repository.
Projects
None yet
Development

No branches or pull requests

6 participants