search

haskell / haskell-language-server

Official haskell ide support via language server (LSP). Successor of ghcide & haskell-ide-engine.
Apache License 2.0
2.65k stars 355 forks source link

Hover docs including links for dependencies #208

Open georgefst opened 4 years ago

georgefst commented 4 years ago

As it stands, it seems that Haddock docs show up for boot libraries, and the project being developed, but not for third party libraries from Hackage.

I would guess (without really knowing anything about the current implementation) that if the dependencies have been installed with documentation (e.g. documentation: True in the global cabal config file), then the logic wouldn't be that different to the way it currently works for boot libraries - i.e. HLS just needs some way to know the path to the .haddock files.

I'd be keen to take a look into this if no one currently is. But I would need some pointers.

jneira commented 4 years ago

A possible workaround is to active documentation generation for all dependant packages adding in the cabal.project:

package * 
  documentation: true

(tip credits for @fendor) It will make the build really slow but it can be done ocasionally.

The hoogle plugin would add docs for dependent packages included in its default set. In the practice they are quite used so you would cover docs for many deps.

pepeiborra commented 4 years ago

Ignoring the hoogle plugin, currently hls/ghcide glean Haddocks from interface files. For interface files to contain Haddocks, ghc must be called with the -haddock flag.

Unfortunately, I don't believe Cabal currently knows about this ghc flag, regardless of the documentation:True setting [1]. You could work around this yourself by telling cabal to use this flag when compiling dependencies in the cabal.project file, or if using stack, in the stack.yaml file.

For Nix, I have sent a PR [2] to add a setting for this, although it will not be the default until 8.12

[1] - https://github.com/haskell/cabal/issues/6825 [2] - https://github.com/NixOS/nixpkgs/pull/91557

jneira commented 4 years ago

Ignoring the hoogle plugin, currently hls/ghcide glean Haddocks from interface files. For interface files to contain Haddocks, ghc must be called with the -haddock flag.

There is a open issue about implementing the plugin, maybe we should closing it with a note.

georgefst commented 4 years ago

Thanks @pepeiborra, I didn't know about that flag!

Not sure what the long-term solution is here then, but for now it seems like it might be worth mentioning in the README that this can be worked around with something like cabal configure --ghc-options=-haddock. Of course, that does cause everything to be rebuilt, and I suspect the build takes a lot longer than without it...

pepeiborra commented 4 years ago

@georgefst better documentation would help, but at the moment my setup is Nix based and I don't use either stack or cabal.project style builds, so I'm not in a good position to give advice about this. If you could send a PR documenting the approach that works for you, it would be a fantastic contribution.

jneira commented 4 years ago

@pepeiborra thanks for the clarification about how hls/ghcide hover works.

I think we should update hls itself cabal.project and stack.yaml dropping the documentation flags and adding the -haddock ghc options cause afaik the main goal for adding them was precisely get docs on hover.

I've tested locally that using -haddock show docs but no using documentation: true, did it work for you @fendor?

jneira commented 3 years ago

As hie-bios can use a specific stack.yaml (and there is a request to be able to set a specific cabal.project), the -haddockoption could be in those specific config files as workaround if the option interferes with normal building (making it slower or fail). Beyond that the unique way to make some progress (avoid the need to generate haddock docs for all dependencies) would be port the hoogle plugin.

georgefst commented 3 years ago

As well as #209, we ought to document that --enable-documentation is required to get the Documentation link to appear with the hover text.

Should we keep things simple and just tell users to enable it globally in addition to -haddock?

jneira commented 2 years ago

As well as #209, we ought to document that --enable-documentation is required to get the Documentation link to appear with the hover text.

Should we keep things simple and just tell users to enable it globally in addition to -haddock?

I think we should add a note about --enable-documentation in the existing section suggesting add -haddock` (https://haskell-language-server.readthedocs.io/en/latest/configuration.html#how-to-show-local-documentation-on-hover)

@georgefst would you like and have time to open a pr adding it?

georgefst commented 2 years ago

@jneira I'm sure it's a fairly quick change but I'm pretty swamped at the moment.

I also don't know the stack syntax off-hand, and there are probably caveats to mention (increased compile times? I'm not sure whether this is negligible in practice).

jneira commented 2 years ago

dont worry will try myself, thanks anyways!

rami3l commented 2 years ago

I don't know if it's related or not, but u/2435191 and I have encountered this strange behavior of base hover docs not working, quote:

image

[...] when hovering over a builtin function only type information comes up, not the actual docstring of the function [...] (Interestingly, the "Documentation Source" link leads me to the web docs, but I don't want to click everytime.)

Original Post

@jneira Do you happen to have any clue on this one?

July541 commented 2 years ago

@rami3l Looks like it's on ghc-9.0, docs is known missing, see https://gitlab.haskell.org/ghc/ghc/-/issues/20903.

rami3l commented 2 years ago

@July541 Thanks a lot for your reply! This turned out to be more complicated than it seems however...

After upgrading the compiler to GHC 9.2.2 (or more precisely, after using stack snapshot nightly-2022-06-06),

VSCode on my Ubuntu box gives me this, which is expected: telegram-cloud-photo-size-5-6163264279076254518-y

However, my Mac gives me this:

image

... and I have no idea how to fix this. If you need more info on this, please feel free to ask me!

July541 commented 2 years ago

@rami3l That's amazing, I always thought that only ghc-9.0 had this problem, but I found both ghc-9.2.2 and 9.2.3 are also not shipping the docs. Worth raising a ticket for ghc devs.

Update: I compiled ghc on local and docs works fine.

rami3l commented 2 years ago

@July541 You mean there could be some problems with the precompiled GHC binaries?

July541 commented 2 years ago

You mean there could be some problems with the precompiled GHC binaries?

Yes I think.

rami3l commented 2 years ago

@July541 My apologies for my not having much experience interacting with the GHC team, but anyway I sent a comment in GHC/#20903.

July541 commented 2 years ago

@rami3l Many thanks for your timely reminder :)

rami3l commented 2 years ago

@July541 Just bring curious: a month later I still didn't get any reply from GHC... Is that thread the wrong place to post?

July541 commented 2 years ago

Just bring curious: a month later I still didn't get any reply from GHC... Is that thread the wrong place to post?

GHC devs are slow to respond to some low-priority jobs I think.

And thanks to ghcup, compiling ghc from source is much easier than before, I've turned to build ghc from source to make docs available.

rami3l commented 1 year ago

Update: This is indeed an issue with prebuilt GHC releases from ghcup. I don't know about newer GHC 9.2.x versions, but updating to GHC 9.4.4 works for me on macOS.

Many thanks to all of you!