Re: [Gtk2hs-users] [commit] update for building docs with haddock

[Duncan C. <dun...@wo...>]

In message <412...@ju...> Jens Petersen <je...@ju...> writes:
> I just committed changes required to build the documentation
> with haddock.  gendoc/ and doc/ have been removed.
> The documentation is built with the "html" target if haddock
> is installed and there is also a "install-html" target.
> Quite a bit more work that I originally thought but at least
> it works for me. :-)

I'll try it out in October. :-)

> I came up with a few minor questions/issues while doing this:
> 
> 1) I couldn't really make up my mind if the Hierarchy module should
> be included in the Gtk documentation or not since it mostly just
> documents the internals?

When I first started building hadock docs I experimented both ways. I think it should be excluded. However this is not wholly possible. Obviously haddock needs to read the Hierarchy.hs module or it'll never see the definitions. We can mark the module as hidden to hadock and it will expand any definitions in the module into which they are imported and references to the data type will go to the local definition. However cross module references will not be done like this, they will still point to the Hierarchy module html documentation.

It's not clear if haddock could be improved to do anything about this since which module should it point to? We know there is some mapping between the types defined in the Hierarchy module and the other modules but I don't think you could work it out automatically very easily. I suppose you could say: data type Foo comes from a hiden module, look for a module in which it's documentation is expanded (re-exported), if there is only one such module link to that, otherwise pick one randomly and emit a warning.

Axel sugested we link not to the data/class type but to the name of the module in which it lives. ie we should say "Button" rather than 'Button'. I've sort of half done this for some of the modules I documented recently, but I'm not sure if it is the ideal solution.

We could always put the definition of the classes in each module using Template Haskell! :-)
This is not a serious suggestion, we would almost certianly end up with circular module imports.

> 2) It occurred to me it would be really cool if we could get
> the documentation to work in devhelp, where all the gtk/gnome
> documentation is more available locally - it is pretty "neat".

I'd never seen devhelp before. It does look good. I'll probably start using it when I get back to binding more stuff rather than using the web site.

> 3) I improved (I hope) the way gconf, glade and sourceview are
> built so that ../gtk/general etc are only searched by c2hs
> and Hierarchy.o etc are not used when compiling them.

That looks better.

Cheers.

Duncan