Re: API documentation from introspection data

[Shaun McCance <shaunm gnome org>]

On Fri, 2012-01-27 at 09:49 +0100, Tomeu Vizoso wrote:
> On Sat, Jan 14, 2012 at 23:30, Colin Walters <walters verbum org> wrote:
> > On Fri, 2012-01-13 at 14:17 +0100, Tomeu Vizoso wrote:
> >> Hi,
> >>
> >> in a bit less than a month from now there will be a hackfest on
> >> documentation in Brno [0]. Has anybody done any further work since
> >> Berlin in generating API documentation in the Mallard format from the
> >> GIR files?
> >
> > I don't think so...I'm not sure what state the work is in.  Probably the
> > first TODO item is to generate a TODO =)  It's really great to hear
> > you're looking at this!
> 
> Shaun, do you have anything to say about this branch?
> 
> http://git.gnome.org/browse/gobject-introspection/log/?h=mallard-templates
> 
> Is it the way to go in your opinion or should we make a change in the direction?

I do think it's the right direction, and I was happy with how it was
panning out when I last worked on it. It just needs more work to get
it producing really great docs.

I did do work in tandem with this on an API reference extension to
Mallard that allowed, for example, automatic links to be formatted
as synopses. And with the conditional processing work I've been
doing, it's possible to write for multiple programming languages
in a single source file.

The real problem with the whole concept is that the gtk-doc docs are
written with the assumption that books are going to be made out of
them. Whenever you have topics extracted from books, you're bound to
have less than optimal results.

For example, we only get docs for things like functions and signals,
not the docs attached to the top of a C file. To gtk-doc, a single
C file is basically a section in a book, and that section can have
introductory material before the various reference subsections.

To get top-notch docs for all bindings, I think we need to dogfood
this with our C docs. That means removing "section" docs, moving
conceptual information into separate pages, and writing with the
assumption that references will be paged into topics that will be
automatically converted for bindings.

--
Shaun