Support more haddock options and maintain haddock index.

[guest]

It would be really cool if it could keep an index up to date as well. (I like to have offline docs for all installed packages, but it's a headache to keep current.)

[duncan]

I guess for a per-user install it could live in $HOME/.cabal/share/doc/index.html

but that's no good for a global install since we cannot steal that name. So where would such an index go?

Note, the same applies to a hoogle index too of course.

The user interface should probably be a flag that we can set in the config file and override on the command line. That UI principle would also apply for a setting to always run tests.

[daniel.is.fischer]

The best I can imagine would be a flag --complete (or something) which would do the equivalent of

runhaskell Setup.hs configure
runhaskell Setup.hs build
runhaskell Setup.hs haddock --hyperlink-source
runhaskell Setup.hs install

on each package in dependency order (since I probably forgot something others would like, --complete is probably not the best choice). Or we could have a flag --haddock to build documentation, but we'd need a way to pass options to haddock, too. Perhaps --with-haddock-options=option1,option2,option3 ? Would that automatically imply --haddock ?

[guest]

FWIW, I think Daniel's idea isn't quite right.

In an ideal world, we could do configure && build && haddock && install - but lots of packages might not work. They may need 2.0 Haddock instead of 0.8; they may use the -- ^{syntax for a 'type' declaration (a known regression in Haddock 2.0, and a fatal bug); or something else entirely. So documentation could *easily* fail to build even when the library/executable works perfectly.}

A better approach would be to build and install, and if that works, go back and try to build Haddocks in a way non-prejudical to the overall build process. (In my shell scripts, it looks something like "configure && build && install; haddock && install".)

[daniel.is.fischer]

I agree, didn't think of haddock failures. So build and install first, if that works try building and installing the docs, too.

[duncan]

--complete isn't very helpful since we're likely to add other things in future like tests, tag files etc.

The nearest thing we have at the moment is features like configure --enable-library-profiling which at configure time asks for things that will be done at build time. So perhaps we want:

cabal install foo --enable-haddock

but then do we also need to be able to control all the haddock flags? There are quite a few of them:

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

Should install just take the union of these things? What about when flags are ambiguous with another command? Both the haddock and hscolour commands have a --css flag.

[waern]

Idea:

If we are lifting flags from other commands into the install flags, we should have different lifting mechanisms for different flags. Take the haddock flags as an example: --hoogle should keep its name but imply --enable-haddock. The other flags should have --haddock- prefixed to their names, but require the --enable-haddock flag to be explicitly set.

Or, we could just disallow these flags and use a configuration file.

In any case, I think all of these flags would be useful also for the install command (the --internal flag being a border-line case).

In the future I hope --enable-haddock (or equivalent mechanism) will be enabled by default.

David

[bfr]

Replying to duncan:

I guess for a per-user install it could live in $HOME/.cabal/share/doc/index.html but that's no good for a global install since we cannot steal that name. So where would such an index go?

I think the question how (and where) to maintain a central documentation index should not be confused with the question of whether to build (and install) documentation at all. Installed API documentation is very useful even w/o a central index, if it can be found under a canonical path derived from the package name.

The real advantage of a central index is accessability. My favourite solution would be a single command e.g. 'hsdoc', which, given a function, a module, type, whatever, finds the haddock docs and displays them in some (user configurable) way (e.g. by starting a web browser). A bit like 'perldoc' but not restricted to plain console output. Much more useful than a central index html page, IMO, specially since you can leverage the shell's history feature, etc.

The natural place of a central index for globally installed packages is wherever ghc-pkg (resp. analogue tools for other implementations) keeps its package database.

Anyway, this should be another ticket. Installing the docs in the first place is useful in and of itself.

[guest]

Hoogle 4 can already do the bits of 'hsdoc' you are mentioning, or at least on a console (the web page bit is a simple addition). Hoogle 4 will require a database for each package that is installed somewhere.

[duncan]

Tue Aug  5 19:05:06 BST 2008  Duncan Coutts <duncan@haskell.org>
  * Initial support for building haddock docs
  No flag to turn it on/off yet.

Wed Aug  6 18:58:34 BST 2008  Duncan Coutts <duncan@haskell.org>
  * Add --enable/disable-documentation flag.
  This addresses most of ticket #206.

Things left to do:

• Allow the option to be set in the config file (see #223)
• Support the various flags of the haddock cabal sub-command (requires agreeing on how that would be presented in the command line interface)
• Maintaining an index of all installed documentation

I think the second two should be split out into their own tickets. I'll do that when the first item is taken care of.

[duncan]

It's now in the config file. Renaming the ticket to reflect the remaining issues and moving it off the immediate milestone.

[duncan]

Closing. The remaining issues are covered by new tickets #516 and #517.

[elga]

*  simyo