make cabal install command support haddock options

[duncan]

Currently the cabal install command supports just --enable-documentation which turns on library docs. The cabal haddock option has various other things like enabling docs for executables, specifying css files, linking to source code etc. Some or perhaps all of these would be useful when installing packages.

This is not fundamentally difficult. The task is just to work out which options are useful (or perhaps all) and how to present the user interface (command line options and config file). Bonus points for a UI that is usable and orthogonal.

See #206 for some of the previous discussion on this topic. See also #516 about maintaining a central haddock module index.

For reference the current haddock command options are:

Flags for haddock:
 -h --help                 Show this help text
 -v --verbose[=n]          Control verbosity (n is 0--3, default verbosity
                           level is 1)
    --builddir=DIR         The directory where Cabal puts generated build files
                           (default dist)
    --hoogle               Generate a hoogle database
    --html-location=URL    Location of HTML documentation for pre-requisite
                           packages
    --executables          Run haddock for Executables targets
    --internal             Run haddock for internal modules and include all
                           symbols
    --css=PATH             Use PATH as the haddock stylesheet
    --hyperlink-source     Hyperlink the documentation to the source code
                           (using HsColour)
    --hscolour-css=PATH    Use PATH as the HsColour stylesheet
    --with-haddock=PATH    give the path to haddock
    --haddock-options=OPTS give extra options to haddock
    --haddock-option=OPT   give an extra option to haddock (no need to quote
                           options containing spaces)

[guest]

I've attached a patch which exposes the following options in cabal install:

--enable-documentation-hoogle (corresponds to --hoogle)
--enable-documentation-source-links (corresponds to --hyperlink-source)
--enable-documentation-executables (corresponds to --executables)
--enable-documentation-internal (corresponds to --internal)
--documentation-css=PATH (corresponds to --css=PATH)
--documentation-hscolour-css=PATH (corresponds to --hscolour-css-PATH)

None of the flags have any effect unless --enable-documentation is set. All of the flags can be set in ~/.cabal/config.

Reiner Pope

[guest]

New patch attached. Same options available, but superior treatment of Hoogle. The hoogle command is now

--enable-hoogle

and can be enabled independently of --enable-documentation. If --enable-documentation and --enable-hoogle are both set, haddock is run twice (once for html documentation; once for hoogle database generation). This has to be done because of #560.

[David]

Yes. Please, please, please incorporate this improvement into the distribution. Even if later on after #560 is fixed there's an even better way to do it, for now, some sort of way of installing source code is needed.

Really, the "documentation: True" option in the config file is barely useful without source code, because most packages do not contain sufficient haddock documentation to be useful without occasionally peeking at the source. Yet one of the great things about haskell is that it's very easy to understand other people's source.

So please either apply this patch, or make --hyperlink-source (#534) the default. Please don't wait for the perfect solution to come along before enabling some sort of way of installing source code with cabal install. The functionality is too critical to defer.

[ross]

To use cabal install for building documentation for packages on hackage would require --html-location, --hyperlink-source and --hoogle.

It would also be handy if variable substitution were applied to --haddock-options (etc): since cabal install may build multiple packages, those packages may require varying configure arguments.

[danfish]

Yes. Please, please, please incorporate this improvement into the distribution. Even if later on after #560 is fixed there's an even better way to do it, for now, some sort of way of installing source code is needed.

At least, for now, make it settable in the config file. It's not so pressing for me anymore since I had the idea to change defaultHaddockFlags in Distribution.Simple.Setup, but I don't want that kind of drastic measure to become an eternal workaround.

[David]

Replying to danfish:

At least, for now, make it settable in the config file. It's not so pressing for me anymore since I had the idea to change defaultHaddockFlags in Distribution.Simple.Setup, but I don't want that kind of drastic measure to become an eternal workaround.

Can you post more detail on your workaround?

Thanks.

[danfish]

Replying to David:

Can you post more detail on your workaround?

Before building Cabal (or GHC), just open Distribution.Simple.Setup.hs in a text editor, go down to defaultHscolourFlags, change hscolourCSS from NoFlag to Flag "~/.cabal/hscolour.css". Go down a little further, in defaultHaddockFlags, change haddockHscolour to Flag True, haddockHscolourCss to Flag "~/.cabal...", haddockInternal/Executables to Flag True if you want that. If you do it when you build GHC, that's all, build and don't worry again (until you get some package on which hscolour chokes). If your GHC is already built, bump the version number in Cabal.cabal, run cabal install in that directory and then cabal install --reinstall cabal-install to get your changes into cabal.

It's evil, but I wanted source-links bad enough to not care :)

[David]

Replying to danfish:

Before building Cabal (or GHC), just open Distribution.Simple.Setup.hs in a text editor...

Can you upload this to hackage?

I'm sure if we had a Cabal-src package that people could enable with ghc-pkg instead of the default Cabal, many people would want to install it. Lots of packages have inadequate or occasionally ambiguous documentation, so I think the lack of easily browsable source code is a real impediment to adoption of Haskell compared to interpreted languages.

[danfish]

Replying to David:

Can you upload this to hackage? I'm sure if we had a Cabal-src package that people could enable with ghc-pkg instead of the default Cabal, many people would want to install it.

I don't think that's a particularly good idea. Using the Cabal library is rather baked-in for at least GHC, and AFAIK, it doesn't like the version it came with to be hidden, let alone uninstalled. Having a package which would basically be a copy of Cabal, but with a different name, would create namespace-pollution by having the same module names and likely confuse GHC as to which package to pick them from. Using different module names, how would one convince the tools to use that library?

I think we should try to make these options settable in the config file. That would require understanding how cabal-install works, when and how it invokes 'cabal haddock' etc. I've taken a few short looks at the source before, but so far, I haven't been able to unravel it (not that I tried too hard yet), the scarcity of documentation and absence of a source-guide don't help getting into it.

[massysett]

Is there something I can do to help out with this ticket? Was there something wrong with the previous patch?

cabal-install is a wonderful idea but due to the lack of this feature I simply don't use it. I wrote a shell script to automatically run the "runhaskell Setup" commands needed to install packages. Haddock docs are an order of magnitude more useful when the source is hyperlinked.

I'm glad to help with this or even put a cash bounty on it. Or, I get the feeling that this comment is going to vanish into the ether where no interested developers will read it, so if any of the cc: people have an idea who to contact, please let me know, thanks :)

[massysett]

Oops, please ignore my last comments...perhaps the latest Cabal can do this...problem is, I can't get it installed on ghc 7.2...

[kosmikus]

Looks to me like this is done:

Sat Oct 15 19:01:01 CEST 2011  Max Bolingbroke <batterseapower@hotmail.com>
  * Allow Haddock to be configured from the 'install' command

Leaving open for now so that I can verify in more detail.

[kosmikus]

Seems to work. Closing.

[DavidMazieres]

Can someone comment as to how to use the new feature.

I've tried putting a bunch of stuff in ~/.cabal/config, but can't get it to hyperlink-source by default.

[DavidMazieres]

At the very least there is still a documentation bug here, as it is impossible to figure out how to enable this feature automatically. I've tried adding each of the following to $HOME/.cabal/config, and none of them work:

haddock-hyperlink-source: True hyperlink-source: True flags: --haddock-hyperlink-source flags: haddock-hyperlink-source flags: --hyperlink-source flags: hyperlink-source

The correct incantation, whatever it is, should be added as a comment to the default .cabal/config file.

[kosmikus]

I don't think it's currently possible to do this via the configuration file.