Haddock: Generate haddock for components

[alexbiehl]

Currently settings documentation: true enables documentation
generation via haddock for your whole package, including tests and benchmarks.
However, there are additional flags to control generation of
documentation for these "second class" documentation targets, which are
currently not honored at the cabal-install side of things. Namely,
tests, benchmarks, executables, etc. provided under the
haddock section in your $CABAL_HOME/config.

This patch adds a more sensible approach to documentation generation
via haddock. The new behaviour works like this:

• Setting documentation: true or passing
  --enable-documentation to cabal-install enables documentation
  for any component in the build plan honoring the respective
  flags for "second class" doc targets from configuration
  or CLI.

• Invoking new-haddock with a target selector will make sure
  the respective flags for "second class" doc targets are set
  correctly. E.g.

     $ new-haddock tests
  

  Will generate documentation for the test suite of your package
  even if you have tests: false in your haddock configuration.

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!

[alexbiehl]

@merijn this should fix your problem.

[merijn]

You're a hero :)

[alexbiehl]

(This resolves #4506)

[23Skidoo]

Needs a changelog note and maybe some tweaks to docs.

[hvr]

As this extends the Setup.hs haddock CLI, this may need version gating in e.g. Distribution.Client.Setup for custom-setup situations when we talk to an external Setup.hs

@23Skidoo this requires making a decision whether we want to target Cabal-2.2.1 or Cabal-3.0 for this (otherwise backward-compatible) CLI enhancement

[merijn]

I've been using this patch the past few days and it seems to work fine, but introduces one silly issue. With documentation: True set it will also rebuild docs every time when you run cabal new-repl which is probably the wrong thing to do.

[alexbiehl]

@merijn Generating documentation with new-repl was present before this patch (c.f.
#5178).

[merijn]

Ok, my bad. I just didn't wanna rebuild all of cabal to test that.

[alexbiehl]

@merijn I corrected the faulty behaviour.

[merijn]

works now \o/

[alexbiehl]

@23Skidoo I added change log entry and documentation.

[merijn]

Incidentally, this PR seems to fix a truckload of issues with new-build's dependency tracking for me. I've been struggling to figure out what was going on with new-repl and new-build being weird about whether stuff had build already, etc. And it all disappears when I use these changes.

[alexbiehl]

Nice! A comment from the cabal gurus would be much appreciated to move this patch forward! Merijn Verstraaten <[email protected]> schrieb am Do., 12. Apr. 2018, 14:23:

…

Incidentally, this PR seems to fix a *truckload* of issues with new-build's dependency tracking for me. I've been struggling to figure out what was going on with new-repl and new-build being weird about whether stuff had build already, etc. And it all disappears when I use these changes. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#5226 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AByiiYU5E4o5b2Qj77xbS4NVqrFmxLKWks5tn0dKgaJpZM4S0s6W> .

[alexbiehl]

@23Skidoo ping

[hvr]

@ezyang did you take into account #5226 (comment) ?

EDIT: ...you didn't, see #5260