Haddock deprecate hscolour, tweak options

[harpocrates]

Please include the following checklist in your PR:

• Patches conform to the coding conventions.
• Any changes that could be relevant to users have been recorded in the changelog.
• The documentation has been updated, if necessary.
• If the change is docs-only, [ci skip] is used to avoid triggering the build bots.

Please also shortly describe how you tested your change. Bonus points for added tests!

---

Small paper-cuts for cabal haddock:

• add a --hyperlinked-source synonym for the --hyperlink-source option and deprecate hscolour (see comments on Support Haddock's hyperlinker #5140)
• pass in --since-qual=external to new enough Haddock versions (see @since includes package name haddock#749)
• add a --quickjump option and enable it when --for-hackage is specified (see QuickJump haddock#683).

I'm still in the process of testing this.

[alexbiehl]

Alec, could you also add the '--quickjump' flag when generating docs for Hackage?

[harpocrates]

@alexbiehl Only for Hackage? Is there any disadvantage to always enabling it?

[alexbiehl]

Not really a good reason but we don't enable hyperlinked source by default either. Alec Theriault <[email protected]> schrieb am Di., 27. März 2018, 19:11:

…

@alexbiehl <https://github.com/alexbiehl> Only for Hackage? Is there any disadvantage to always enabling it? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#5236 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AByiidZU3HOUwWe8fycSFY0CQNFytmrnks5tinK4gaJpZM4S9SZB> .

[gbaz]

Quickjump doesn't work with local docs at the moment, due to ajax restrictions :-/

An alternate local mode that embedded the quickjump data thus bypassing the xhr request, just for local docs, might be quite nice. (in fact, why can't that be done in general?)

[harpocrates]

I'm sold on enabling it by default only in --for-hackage.

I'll add --quickjump as a separate flag, and --for-hackage will imply it.

[alexbiehl]

The reason to have it separately from the html is that we want Hackage to read the index on the package page. Also we pay n times the index if we store them in each html file. gbaz <[email protected]> schrieb am Di., 27. März 2018, 19:21:

…

Quickjump doesn't work with local docs at the moment, due to ajax restrictions :-/ An alternate local mode that embedded the quickjump data thus bypassing the xhr request, just for local docs, might be quite nice. (in fact, why can't that be done in general?) — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#5236 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AByiiZlqTpEP1G_uH7-6OF2Q8iabXxnkks5tinUvgaJpZM4S9SZB> .

[gbaz]

right -- i'm not suggesting to embed directly. I'm suggesting to use a <link> tag or something to a js file for those cases. So you can still share it. And hackage can still read it (either by embedding the js file itself, or by xhr to a separate json file). just move to a load mechanism that isn't dynamic, but is static with the page, to avoid xhr restrictions.

[23Skidoo]

I'm +1 on always enabling hyperlink-source, btw.

[harpocrates]

I am strongly against always enabling hyperlink-source - it can be quite slow for large generated source files. Once haskell/haddock#758 gets fixed, I'll go from "strongly against" to "don't care".

[23Skidoo]

Good point, let's wait for that issue to get fixed.

[alexbiehl]

Thanks Alec!

[harpocrates]

I'll merge as soon as all CI is green.

@23Skidoo Is the deprecation message around hscolour good enough? I looked for other similar instances of deprecation but didn't really find any.

[harpocrates]

@alexbiehl Which version of Haddock should I expect the since annotation stuff to be in? 2.19.1 or 2.20.0?

[alexbiehl]

@harpocrates Make it 2.20 Alec Theriault <[email protected]> schrieb am Mi., 28. März 2018, 20:14:

…

@alexbiehl <https://github.com/alexbiehl> Which version of Haddock should I expect the since annotation stuff to be in? 2.19.1 or 2.20.0? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#5236 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AByiiXB225Pa_DVeliN3X3F1u5otLKnCks5ti9MEgaJpZM4S9SZB> .

[harpocrates]

I let the tests run for 22c11f1 and Travis had only a handful of failures, all with error messages that cannot be related to that commit. Since then, all I've done is bump up the required Haddock for --since-qual (as per Alex's comment).

@23Skidoo Does this look OK to merge now?

[alexbiehl]

This looks good. @23Skidoo can we merge this?

[harpocrates]

I've rebased on master. Now that #5261 is merged, I think this should be OK again.

[23Skidoo]

Rebased against master.

[23Skidoo]

Merged, thanks!