developer docs with haddock: cabal or make?
hello, for the project I am doing, I would like to be able to create two documentation sets: - the user documentation, done with normal Setup.hs --haddock and - the developer documentation, where all modules are exposed and haddock is run with --ignore-all-exports What is the right way to do this? I see two options, but both are somewhat clumsy: 1. Write a custom Setup.hs, using the Cabal library. Ideally, it would accept a new command, like "Setup.hs --haddock-devel". However Cabal doesn't seem to be designed for adding new commands or options to them - the interface is hardcoded. For instance, I can't add a command in such a way that it would be listed alongside others when calling "Setup.hs --help". 2. Call haddock from a makefile. This is a one-liner with haddock 0.8, but not with haddock 2.0 and above. The problem is that haddock 2.0 only supports --read-interface and doesn't support --use-package any more. Thus I have to find all the haddock interfaces by hand, for instance by calling ghc-pkg for each library I depend on. This is of course straightforward, but I feel that it shouldn't be my job. Any comments or ideas? Cheers, Misha
On Mon, 2008-05-26 at 15:26 +0200, Misha Aizatulin wrote:
hello,
for the project I am doing, I would like to be able to create two documentation sets: - the user documentation, done with normal Setup.hs --haddock and - the developer documentation, where all modules are exposed and haddock is run with --ignore-all-exports
What is the right way to do this? I see two options, but both are somewhat clumsy:
The latest version of Cabal has a new flag for the haddock command: --internal Run haddock for internal modules and include all symbols I think that does what you're asking for. You'd say: $ cabal haddock --internal This will be in the Cabal-1.4 release or you can get the darcs version now. Duncan
for the project I am doing, I would like to be able to create two documentation sets: - the user documentation, done with normal Setup.hs --haddock and - the developer documentation, where all modules are exposed and haddock is run with --ignore-all-exports
The latest version of Cabal has a new flag for the haddock command:
--internal Run haddock for internal modules and include all symbols
wow, it's cool, how things happen right when you need them! :) This new flag should make me happy indeed. I am still interested if there is any plan to facilitate adding custom Setup commands? The author might like to run something on the code that isn't handled by Cabal already. In a Makefile you just add a new target, but there is no easy way to do so in a Setup.hs yet. One particular example would be the install-docs command, that installs only the documentation. Because of it's absence, ghc currently doesn't install the library documentation, when you do "make install-docs". Cheers, Misha
participants (2)
-
Duncan Coutts -
Misha Aizatulin