Support more haddock options and maintain haddock index.

[bos]

(Imported from Trac #206, reported by guest on 2008-01-13)

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

[bos]

(Imported comment by @dcoutts on 2008-01-13)

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.

[bos]

(Imported comment by daniel.is.fischer on 2008-01-13)

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 ?

[bos]

(Imported comment by guest on 2008-06-18)

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

[bos]

(Imported comment by daniel.is.fischer on 2008-06-19)

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

[bos]

(Imported comment by @dcoutts on 2008-06-19)

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

[bos]

(Imported comment by @waern on 2008-06-19)

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

[bos]

(Imported comment by bfr on 2008-06-26)

Replying to @dcoutts:

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.

[bos]

(Imported comment by guest on 2008-07-02)

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.

[bos]

(Imported comment by @dcoutts on 2008-07-03)

Tue Aug  5 19:05:06 BST 2008  Duncan Coutts <[email protected]>
- Initial support for building haddock docs
  No flag to turn it on/off yet.
  Wed Aug  6 18:58:34 BST 2008  Duncan Coutts <[email protected]>
- 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 setup haddock ignores LANGUAGE CPP pragma #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.

[bos]

(Imported comment by @dcoutts on 2008-08-06)

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

[bos]

(Imported comment by @dcoutts on 2008-08-22)

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