Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

make cabal install command support haddock options #510

Closed
bos opened this Issue · 17 comments

2 participants

@bos
Owner

(Imported from Trac #517, reported by @dcoutts on 2009-03-03)

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)
@bos
Owner

(Imported comment by guest on 2009-03-03)

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

@bos
Owner

(Imported comment by guest on 2009-06-03)

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.

@bos
Owner

(Imported comment by David on 2009-06-03)

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.

@bos
Owner

(Imported comment by ross on 2009-09-27)

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.

@bos
Owner

(Imported comment by danfish on 2010-01-15)

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.

@bos
Owner

(Imported comment by David on 2010-02-27)

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.

@bos
Owner

(Imported comment by danfish on 2010-02-27)

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 :)

@bos
Owner

(Imported comment by David on 2010-02-27)

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.

@bos
Owner

(Imported comment by danfish on 2010-03-02)

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.

@bos
Owner

(Imported comment by massysett on 2010-03-02)

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 :)

@bos
Owner

(Imported comment by massysett on 2011-11-28)

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...

@bos
Owner

(Imported comment by @kosmikus on 2011-11-28)

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.
@bos
Owner

(Imported comment by @kosmikus on 2012-03-06)

Seems to work. Closing.

@bos
Owner

(Imported comment by DavidMazieres on 2012-04-16)

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.

@bos
Owner

(Imported comment by DavidMazieres on 2012-04-16)

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.

@bos
Owner

(Imported comment by @kosmikus on 2012-04-20)

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

@tibbe
Owner

Lets continue the config file part in #1585.

@tibbe tibbe closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.