Rewrite Documentation/Source links on hover to use local hoogle/hackage if available on nix and otherwise

[ParetoOptimalDev]

Is your enhancement request related to a problem? Please describe.

This request is similar to #208, but slightly different? At least the fact that this issue is focused on nix support makes it different, but the implementation of this could satisfy both issues I believe.

Even when I have a local instance of hoogle running at localhost:8888 the links I click for source and documentation go to http://haskell.org.

NOTE: I use nix's withHaddock feature for this

For instance I'm linked to:

https://hackage.haskell.org/package/apecs-0.9.4/docs/Apecs-Util.html#v:newEntity_

When I'd prefer to be linked to:

http://localhost:8888/file/nix/store/pmyb1ayz7vxlmim1bd12sjpss3s7pddy-apecs-0.9.4-doc/share/doc/apecs-0.9.4/html/Apecs.html#v:newEntity_

Describe the solution you'd like

For HLS to check to see if a hoogle instance is running and if it's fingerprint is a nix server, rewrite urls like:

- https://hackage.haskell.org/package/apecs-0.9.4/docs/Apecs-Util.html#v:newEntity_
+ http://localhost:8888/file/nix/store/pmyb1ayz7vxlmim1bd12sjpss3s7pddy-apecs-0.9.4-doc/share/doc/apecs-0.9.4/html/Apecs.html#v:newEntity_

And for source:

- https://hackage.haskell.org/package/apecs-0.9.4/docs/src/Apecs.Util.html#newEntity_
+ http://localhost:8888/file/nix/store/pmyb1ayz7vxlmim1bd12sjpss3s7pddy-apecs-0.9.4-doc/share/doc/apecs-0.9.4/html/src/Apecs.Util.html#newEntity_

Looking at the above, the common replacement within the urls is:

- /package/apecs-0.9.4/docs
+/file/nix/store/pmyb1ayz7vxlmim1bd12sjpss3s7pddy-apecs-0.9.4-doc/share/doc/apecs-0.9.4/html

You can get this variable in recent versions of Nix's haskellPackages from the environmental variable $NIX_GHC_DOCDIR.

NOTE: I believe the code to change is in Development.IDE.Spans.Documentation.getDocumentationsTryGhc

Describe alternatives you've considered

A workaround described here:

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

package * 
  documentation: true

To be frank though, I'd just never do that and probably forget it was ever an option.

[alexfmpe]

Would also like this due to having some dependencies that aren't present in hackage at all.
What if instead of HLS rewriting links it accepted a "haddocks root" flag, defaulting to hackage but allowing nix setups to override it with the same root used in the links rendered by nix-based local hoogle?
That way HLS doesn't need to be nix aware, it would just stop forcing hackage as a decision.

[fendor]

I was thinking a little bit about this, and what would the haddock root look like? Given the example above, providing a root location is easy, but nix stores the documentation in /nix/store/<hash>-<pkgname>/share/doc. There is no common root that we could use, afaict.

[alexfmpe]

Hmm true, we'd need to be able to override on a per-package basis. Which makes some sense I guess, you could have most packages coming from hackage but a few hosted on an org-specific repository?

So the flag would need to be a filepath to a file with contents similar to

apecs-0.9.4 -> /file/nix/store/pmyb1ayz7vxlmim1bd12sjpss3s7pddy-apecs-0.9.4-doc/share/doc/apecs-0.9.4/html
example-0.1.1 -> /file/nix/store/<hash>-example-0.1.1-doc/share/doc/example-0.1.1/html

[alexfmpe]

After some more thought, I realised HLS probably should be getting the urls from haddock-interfaces/ haddock-html whenever possible, and give that priority over hackage.

$ ghc-pkg describe text

haddock-interfaces:
    /nix/store/phnrbf9zvf8nl6wrhbh3qwgn9d2q7rhl-ghc-9.4.8-doc/share/doc/ghc/html/libraries/text-2.0.2/text.haddock

haddock-html:
    /nix/store/phnrbf9zvf8nl6wrhbh3qwgn9d2q7rhl-ghc-9.4.8-doc/share/doc/ghc/html/libraries/text-2.0.2

For the specific case of nix-built dependencies, this seems to solve the entire problem as every dep ends up in the package database.

Following the above source directions by @ParetoOptimalDev, I ended up very surprised seeing HLS is already doing this:

haskell-language-server/ghcide/src/Development/IDE/Spans/Documentation.hs

Lines 157 to 161 in 838a51f

	lookupHtmls :: HscEnv -> Unit -> Maybe [FilePath]
	lookupHtmls df ui =
	-- use haddockInterfaces instead of haddockHTMLs: GHC treats haddockHTMLs as URL not path
	-- and therefore doesn't expand $topdir on Windows
	map takeDirectory . unitHaddockInterfaces <$> lookupUnit df ui

However, vscode-haskell hardcodes to hackage. On the other hand, haskell-mode seems to produce the right links - not sure whether it's getting them from HLS or something else. I only use emacs/vscode so don't know the status on extensions for other editors.