search

haskell / haddock

Haskell Documentation Tool
www.haskell.org/haddock/
BSD 2-Clause "Simplified" License
361 stars 242 forks source link

CONTRIBUTING: How to apply modified haddock to packages? #1617

Closed amigalemming closed 1 month ago

amigalemming commented 8 months ago

Could you please add a line to CONTRIBUTING.md, telling how to actually apply a modified haddock to Cabal packages? I tried:

mypkg$ cabal-3.10 haddock  --with-ghc=/usr/local/ghc/9.4.7/bin/ghc --with-haddock=/tmp/my-custom-haddock-build/haddock

But I get:

...
Configuring library for base-orphans-0.9.1..
Preprocessing library for base-orphans-0.9.1..
Building library for base-orphans-0.9.1..
[1 of 2] Compiling Data.Orphans.Prelude ( src/Data/Orphans/Prelude.hs, dist/build/Data/Orphans/Prelude.o, dist/build/Data/Orphans/Prelude.dyn_o )
[2 of 2] Compiling Data.Orphans     ( src/Data/Orphans.hs, dist/build/Data/Orphans.o, dist/build/Data/Orphans.dyn_o )
Preprocessing library for base-orphans-0.9.1..
Running Haddock on library for base-orphans-0.9.1..
Warning: --source-* options are ignored when --hyperlinked-source is enabled.
 100% (  1 /  1) in 'Data.Orphans'
Haddock's resource directory does not exist!
...
amigalemming commented 8 months ago

Found this related ticket: https://github.com/haskell/haddock/issues/519 But how can I pass haddock options through cabal haddock? Cabal seems to ignore options --haddock-option and --haddock-options.

Kleidukos commented 8 months ago

@amigalemming can I encourage you to open a ticket on the cabal tracker? This seems more related to how these options are processed by cabal. :)

Kleidukos commented 8 months ago

That being said once we have the answer I'd be more than happy to put the instructions in the CONTRIBUTING file

amigalemming commented 8 months ago

Hm, today Cabal's haddock-option passing works. Strange. I have checked with cabal's -v option. My command line from initial post now works by passing haddock's --lib option, however it does not work with a symbolic link and it needs an absolute path and tilde expansion is not applied (the latter one is certainly a shell issue). So this one works for me:

mypkg$ cabal-3.10 haddock  --with-ghc=/usr/local/ghc/9.4.7/bin/ghc --with-haddock=/tmp/my-custom-haddock-build/haddock --haddock-option="--lib=$HOME/haddock-git/haddock-api/resources"