Implementation guidance for haskell_doc features

[brendanhay]

I currently use a fork of rules_haskell with modifications to the default options being passed to haddock, since haskell_doc doesn't expose a haddockopts, args, or similar attribute. This is used to omit or replace the default Haddock generated index, which with the default --gen-index and --gen-contents options, generates certain individual HTML files with sizes of 120~ MiB or more. Therefore I either omit the index by removing the --gen-index option or supply my own target/label to --use-index.

I'd like extend haskell_doc with analogues for the --use-contents, --use-index, --theme, and --no-warnings Haddock options, but there a couple of potential implementation strategies I'm aware of:

1. Implement a subset of the total Haddock options as new haskell_doc attributes, ensuring that the exposed options interact correctly with the rules internal options added via args.add.... There are a lot of useful/sensible Haddock options to expose (10 - 20, reasonably), so the new interface would be quite "large".
2. Expose an args (or haddockopts) string_list which supports Make variable substitution. While strictly more powerful/complete, I'm uncertain how options would be added or preferred over default options such as --title. What happens if you want a different --title and supply this via args - how does this interact with the rules-supplied --title={0}".format(ctx.attr.name)?.

[aherrmann]

It doesn't address the general case, but just to mention it, you can define global haddock flags on the toolchain, e.g. on haskell_register_ghc_nixpkgs.

I agree, being able to set custom haddock flags would be good. I'd say the precedent that haskell_library and similar establish is that users can set flags directly, with make variable substitution, like you propose in 2. The name haddockopts sounds like a good choice, following the ghcopts pattern. Something to beware of is that haddock is not invoked by the haskell_doc rule, but by an aspect. So, the haddockopts attribute would probably need to be placed on the haskell_library rule. (Aspects can be configured through attributes on the requesting rule, but this is quite limited)

Yes, the conflict case is important to consider. We could follow the toolchain provided flags and insert per target user provided flags directly after. This way, if haddock allows a flag to override a previous flag, the user would have that option. In the specific case of --title, where the default is inferred based on other attributes, a dedicated attribute seems reasonable. How many such cases do you see?