[Hackage] #206: cabal-install should be able to generate haddock docs
#206: cabal-install should be able to generate haddock docs ---------------------------------+------------------------------------------ Reporter: guest | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Component: cabal-install tool | Version: 1.2.3.0 Severity: normal | Keywords: Difficulty: normal | Ghcversion: 6.8.2 Platform: Linux | ---------------------------------+------------------------------------------ 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.) -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/206 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#206: cabal-install should be able to generate haddock docs ---------------------------------+------------------------------------------ Reporter: guest | Owner: duncan Type: enhancement | Status: assigned Priority: normal | Milestone: Component: cabal-install tool | Version: 1.2.3.0 Severity: normal | Resolution: Keywords: | Difficulty: normal Ghcversion: 6.8.2 | Platform: Linux ---------------------------------+------------------------------------------ Changes (by duncan): * status: new => assigned * owner: => duncan Comment: 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. -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/206#comment:1 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#206: cabal-install should be able to generate haddock docs ---------------------------------+------------------------------------------ Reporter: guest | Owner: duncan Type: enhancement | Status: assigned Priority: normal | Milestone: Cabal-1.4 Component: cabal-install tool | Version: 1.2.3.0 Severity: normal | Resolution: Keywords: | Difficulty: normal Ghcversion: 6.8.2 | Platform: ---------------------------------+------------------------------------------ Changes (by duncan): * platform: Linux => * milestone: => Cabal-1.4 -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/206#comment:2 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#206: cabal-install should be able to generate haddock docs ---------------------------------+------------------------------------------ Reporter: guest | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Cabal-1.4 Component: cabal-install tool | Version: 1.2.3.0 Severity: normal | Resolution: Keywords: | Difficulty: normal Ghcversion: 6.8.2 | Platform: ---------------------------------+------------------------------------------ Changes (by duncan): * status: assigned => new * owner: duncan => -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/206#comment:3 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#206: cabal-install should be able to generate haddock docs ---------------------------------+------------------------------------------ Reporter: guest | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Cabal-1.4 Component: cabal-install tool | Version: 1.2.3.0 Severity: normal | Resolution: Keywords: | Difficulty: normal Ghcversion: 6.8.2 | Platform: ---------------------------------+------------------------------------------ Changes (by guest): * cc: avatar@hot.ee (added) -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/206#comment:4 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#206: cabal-install should be able to generate haddock docs ---------------------------------+------------------------------------------ Reporter: guest | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Cabal-1.4 Component: cabal-install tool | Version: 1.2.3.0 Severity: normal | Resolution: Keywords: | Difficulty: normal Ghcversion: 6.8.2 | Platform: ---------------------------------+------------------------------------------ Comment (by 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 ? -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/206#comment:5 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#206: cabal-install should be able to generate haddock docs ---------------------------------+------------------------------------------ Reporter: guest | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Cabal-1.4 Component: cabal-install tool | Version: 1.2.3.0 Severity: normal | Resolution: Keywords: | Difficulty: normal Ghcversion: 6.8.2 | Platform: ---------------------------------+------------------------------------------ Changes (by guest): * cc: avatar@hot.ee (removed) * cc: gwern0@gmail.com (added) Comment: 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".) -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/206#comment:6 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#206: cabal-install should be able to generate haddock docs ---------------------------------+------------------------------------------ Reporter: guest | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Cabal-1.4 Component: cabal-install tool | Version: 1.2.3.0 Severity: normal | Resolution: Keywords: | Difficulty: normal Ghcversion: 6.8.2 | Platform: ---------------------------------+------------------------------------------ Comment (by 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. -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/206#comment:7 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#206: cabal-install should be able to generate haddock docs ---------------------------------+------------------------------------------ Reporter: guest | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Cabal-1.4 Component: cabal-install tool | Version: 1.2.3.0 Severity: normal | Resolution: Keywords: | Difficulty: normal Ghcversion: 6.8.2 | Platform: ---------------------------------+------------------------------------------ Changes (by guest): * cc: avatar@hot.ee (added) -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/206#comment:8 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#206: cabal-install should be able to generate haddock docs ---------------------------------+------------------------------------------ Reporter: guest | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Cabal-1.4 Component: cabal-install tool | Version: 1.2.3.0 Severity: normal | Resolution: Keywords: | Difficulty: normal Ghcversion: 6.8.2 | Platform: ---------------------------------+------------------------------------------ Comment (by 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. -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/206#comment:9 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#206: cabal-install should be able to generate haddock docs ---------------------------------+------------------------------------------ Reporter: guest | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Cabal-1.4 Component: cabal-install tool | Version: 1.2.3.0 Severity: normal | Resolution: Keywords: | Difficulty: normal Ghcversion: 6.8.2 | Platform: ---------------------------------+------------------------------------------ Comment (by 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 -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/206#comment:10 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#206: cabal-install should be able to generate haddock docs ---------------------------------+------------------------------------------ Reporter: guest | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Cabal-1.4 Component: cabal-install tool | Version: 1.2.3.0 Severity: normal | Resolution: Keywords: | Difficulty: normal Ghcversion: 6.8.2 | Platform: ---------------------------------+------------------------------------------ Changes (by tibbe): * cc: johan.tibell@gmail.com (added) -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/206#comment:11 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#206: cabal-install should be able to generate haddock docs ---------------------------------+------------------------------------------ Reporter: guest | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Cabal-1.4 Component: cabal-install tool | Version: 1.2.3.0 Severity: normal | Resolution: Keywords: | Difficulty: normal Ghcversion: 6.8.2 | Platform: ---------------------------------+------------------------------------------ Comment (by bfr): Replying to [comment:1 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. -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/206#comment:12 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#206: cabal-install should be able to generate haddock docs ---------------------------------+------------------------------------------ Reporter: guest | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Cabal-1.4 Component: cabal-install tool | Version: 1.2.3.0 Severity: normal | Resolution: Keywords: | Difficulty: normal Ghcversion: 6.8.2 | Platform: ---------------------------------+------------------------------------------ Comment (by 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. -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/206#comment:13 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#206: cabal-install should be able to generate haddock docs
---------------------------------+------------------------------------------
Reporter: guest | Owner:
Type: enhancement | Status: new
Priority: normal | Milestone: Cabal-1.4
Component: cabal-install tool | Version: 1.2.3.0
Severity: normal | Resolution:
Keywords: | Difficulty: very easy (<1 hour)
Ghcversion: 6.8.2 | Platform:
---------------------------------+------------------------------------------
Changes (by duncan):
* difficulty: normal => very easy (<1 hour)
Comment:
{{{
Tue Aug 5 19:05:06 BST 2008 Duncan Coutts
#206: Support more haddock options and maintain haddock index. ---------------------------------+------------------------------------------ Reporter: guest | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Component: cabal-install tool | Version: HEAD Severity: normal | Resolution: Keywords: | Difficulty: normal Ghcversion: 6.8.2 | Platform: ---------------------------------+------------------------------------------ Changes (by duncan): * difficulty: very easy (<1 hour) => normal * summary: cabal-install should be able to generate haddock docs => Support more haddock options and maintain haddock index. * version: 1.2.3.0 => HEAD * milestone: Cabal-1.4 => Comment: It's now in the config file. Renaming the ticket to reflect the remaining issues and moving it off the immediate milestone. -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/206#comment:15 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#206: Support more haddock options and maintain haddock index. ---------------------------------+------------------------------------------ Reporter: guest | Owner: Type: enhancement | Status: closed Priority: normal | Milestone: Component: cabal-install tool | Version: HEAD Severity: normal | Resolution: wontfix Keywords: | Difficulty: normal Ghcversion: 6.8.2 | Platform: ---------------------------------+------------------------------------------ Changes (by duncan): * status: new => closed * resolution: => wontfix Comment: Closing. The remaining issues are covered by new tickets #516 and #517. -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/206#comment:16 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
participants (1)
-
Hackage