[skip circleci] Update code documentation generation instructions

[jneira]

• The cabal command generates:

documentation: True

package *
  documentation: True
  ghc-options: -haddock

program-options
  ghc-options: -haddock

• --enable-documentation is needed to make the hover show the links to open docs and sources

  • would be great to know why 🙂

• I am not sure if stack instructions will work, i.e. show the links see #Documentation and Source links for local dependencies #1866

//cc @georgefst @DunetsNM @eirikm

[georgefst]

We should also mention that documentation: True can be set globally in ~/.cabal/config.

[jneira]

We should also mention that documentation: True can be set globally in ~/.cabal/config.

yeah, thanks for noting it

[jneira]

I tried

  ```yaml
  build:
    haddock: true

and the links are not shown for local package definitions.
@georgefst do you know why cabal's --enable-documentation makes them work?

[michaelpj]

Changes look fine, although I haven't tried any of it!

[georgefst]

@georgefst do you know why cabal's --enable-documentation makes them work?

Not really, no.

[georgefst]

On reflection, I think we should actually avoid merging this until #2194 is fixed somehow. There's not much point advertising a feature that's completely broken.

[jneira]

I've tried a cabal project removing and adding documentation: True and i not see any effect in documentation links: they are shown for dependencies and no for local packages definition in both cases.
I did a cabal clean and remove hie-bios cache between tests just in case.

[georgefst]

Behaviour here is very odd and needs further investigation. --enable-documentation is required for the Documentation link to show up, even though (as of a recent change?) that link leads to a webpage rather than the local copy which --enable-documentation caused to be built.

[jneira]

even though (as of a recent change?) that link leads to a webpage rather than the local copy which --enable-documentation caused to be built.

there is a vscode config option to open docs locally as before, but we decided to set open in hackage the default due to broken links

[jneira]

Behaviour here is very odd and needs further investigation.

agree

[georgefst]

I've tried a cabal project removing and adding documentation: True and i not see any effect in documentation links: they are shown for dependencies and no for local packages definition in both cases. I did a cabal clean and remove hie-bios cache between tests just in case.

Huh, that's weird. I'm on Linux, GHC 8.10.7, Cabal 3.6.0.0, FWIW. Can easily reproduce with a simple exe package that has just one dependency on extra: --enable-documentation makes the difference as to whether I see the Documentation link for splitOn.

[jneira]

thanks , will try to reproduce, just to be sure the behaviour is:

• with no config options, there is no docs neither links on hover
• with --ghc-options=-haddock you get docs but no link
• with --enable-documentation you get the link but no docs
• with both (and only with both) --ghc-options=-haddock --enable-documentation you get docs and links
  ??

[georgefst]

thanks , will try to reproduce, just to be sure the behaviour is:

* with no config options, there is no docs neither links on hover

* with `--ghc-options=-haddock` you get docs but no link

* with `--enable-documentation` you get the link but no docs

* with both (and only with both) `--ghc-options=-haddock --enable-documentation` you get docs and links
  ??

Correct.

[georgefst]

even though (as of a recent change?) that link leads to a webpage rather than the local copy which --enable-documentation caused to be built.

there is a vscode config option to open docs locally as before, but we decided to set open in hackage the default due to broken links

Aha, that explains a few things! See #2194 (comment).

[georgefst]

On reflection, I think we should actually avoid merging this until #2194 is fixed somehow. There's not much point advertising a feature that's completely broken.

I'm also wary of haskell/cabal#7690 (comment), though I have no idea what's going on there.