From: Jens P. <je...@ju...> - 2004-08-07 12:35:25
|
Hi, I have just been playing with generating the documentation for gtk with Haddock and it is seems to work pretty nicely. Just a couple of things I noticed: the preprocessor code in Gtk.hs (and FFI.hs which I guess can be excluded but anyway) seems to make haddock unhappy... presumably it needs to be preprocessed in advance or haddock could be taught to do that I suppose? Anyway it would be nice to go ahead and make the makefiles support building the documentation with haddock by default I think. Is there anything that's needs to be done before that change can be made? Jens |
From: Duncan C. <dun...@wo...> - 2004-08-07 13:03:00
|
On Sat, 2004-08-07 at 13:35, Jens Petersen wrote: > I have just been playing with generating the documentation > for gtk with Haddock and it is seems to work pretty nicely. Yes, it's quite good. I'm less sure about some of the other modules, mogul, gconf etc. They'll come along if we get the main gtk stuff building regularly. We would probably want to take advantage of haddock's facility to build docs for different packages separately, but generate & use interface files so that the packages can have references to each other. I guess it'd be the same as the ghc-package dependencies, ie mogul and all the other extra packages depend on gtk. > Just a couple of things I noticed: the preprocessor code > in Gtk.hs (and FFI.hs which I guess can be excluded but > anyway) seems to make haddock unhappy... presumably it needs > to be preprocessed in advance or haddock could be taught > to do that I suppose? Someone asked if haddock would support that. Simon says just preprocess it yourself. So we should do that too. Actually we probably want to exclude FFI from the docs anyway, but the GTK.hs one would make a good contents page - even better than the standard one since we can group them by functionality and add comments. > Anyway it would be nice to go ahead and make the makefiles > support building the documentation with haddock by default > I think. Is there anything that's needs to be done before > that change can be made? I don't think there's anything else to be done. I had a go at converting configure.in to find haddock and the doc/Makefile to build it but makefiles tend to give me the fear so I didn't finish that properly. I think you're our resident conf/make guru so if you want to do that it'd be great. Haddock allows you to add a prologue to the top of the index it generates. So my makefile did this: #add a version header to the prologue text prologue.txt.complete : prologue.txt echo "Documentation for Gtk2Hs version $(VERSION)" | \ cat - prologue.txt > prologue.txt.complete all : haddock --html --title=Gtk2Hs --package=gtk2hs \ --prologue=prologue.txt.complete \ `find ../gtk/ -name '*.hs' ! -name 'FFI.hs' ! -name 'Gtk.hs'` (I was just ignoring the two that need to be preprocessed) Duncan |