[Haskell-beginners] Package Documentation (Haddock)

[Daniel Fischer]

On Thursday 18 November 2010 21:20:45, Bastian Erdnüß wrote:
> On Nov 18, 2010, at 20:46, Daniel Fischer wrote:
> > On Thursday 18 November 2010 20:25:26, Bastian Erdnüß wrote:
> >> Hi,
> >>
> >> I found the Haddock documentation to the packages that came with the
> >> Haskell Platform locally on my machine.
> >>
> >> 1) It's a little bit uncomfortable to always pick the right one by
> >> hand. Is there a more comfortable way like doing e.g. 'haddock
> >> Data.List' (that's not working) to direct to the documentation of a
> >> certain module?
> >
> > Sorry, I don't understand what you want.
>
> No matter.  Maybe me not either.
>
> > To view the haddocks, there's an index.html in the docdir, bookmark
> > that in your browser and click from there.
>
> That works for the Modules that came with GHC but not for the others in
> the Haskell Platform.  (On the Mac with the Haskell Platform there came
> the GHC.framework and the HaskellPlatform.framework.  In the doc folder
> of the GHC.framework is a central index.html in the doc folder of the
> HaskellPlatform, it isn't.)  However, still an improvement.
>

Hrrmphh. I thought the platform would come with docs. It probably does, 
they're just hiding. You can try

$ locate Graphics-Rendering-OpenGL.html

(random module from one of the HP libs, maybe locate has a different name 
on the Mac; find -name should work, but locate tends to be faster).

If that reveals something, the doc root should be a few directories up.
If not, the platform may have come without docs, complain :)

> > If you want to generate haddocks for your project(s) and have it link
> > to the modules you used, the simplest way is to create a .cabal file
> > and let cabal take care of directing haddock to the installed docs
> > (you can do it manually with --read-interface flags, but letting cabal
> > figure out the correct flags is easier).
>
> I'm not that far yet with Haskell.  But I mark that note for later.
>
> >> 2) I cannot find the documentation to the packages I post installed
> >> with cabal.  I tried to build them using e.g. 'cabal haddock Yampa'
> >> but that's not working.  How do I do it right?
> >
> > Edit your ~/.cabal/config, set
> >
> > documentation: True
>
> I just did.
>

A propos,

library-profiling: True

is probably also a good idea, if you want to do any profiling (and sooner 
or later you will), you need the libraries you use built for profiling too.

> > there, then cabal builds docs for all packages it installs
> > automatically (and creates a comprehensive index in
> > ~/.cabal/share/doc). Unfortunately, it doesn't build docs for packages
> > it previously installed, so you'd have to reinstall them or create the
> > haddocks manually [the latter may need unpacking the packages]. If you
> > haven't installed many packages yet, reinstalling is probably the
> > simpler route.
>
> Well, there are to much to reinstall everyone per hand, but not to much
> if there is a magic command like 'cabal upgrade --reinstall --all' to do
> it all at once.  Any help how to do that?
>

A shell script?

$ cat reinstallEverything.sh
PACKS=`ghc-pkg list --user | grep -v /home` 
# remove the location of user-db
cabal install --reinstall --dry-run $PACKS;

If the dry-run output doesn't look too frightening, remove the --dry-run 
flag and let it reinstall what you have. (Assumes that the platform 
packages are registered in the global package db, otherwise it would try to 
reinstall the entire platform too, which would probably not be ideal.)

> >> Thanks for your help in advance,
> >> Bastian
>
> ^^ still valid