Re: API documentation from introspection data

[Mikkel Kamstrup Erlandsen <mikkel kamstrup gmail com>]

On 18 February 2012 07:47, Tomeu Vizoso <tomeu tomeuvizoso net> wrote:
> ...snip...
> We started generating DocBook from GIR files, trying to mimic GTK-Doc
> as much as possible. Progress was slow and we had quite some problems
> trying to rescue the DocBook that is embedded in the C sources.
>
> Shaun had already been working on using Mallard for the GNOME API docs
> and at the g-i hackfest last year he quickly hacked up the initial
> g-ir-doc-tool to output Mallard. Because it is higher level than
> DocBook and because the yelp tools already had some support for API
> references, it looked much more advanced than the DocBook generator
> and it was clear to us that Mallard could do the job just fine.

Allow me to be frank; I don't see reasons other than academics to have
an intermediate format. GIR is quite simple and suitable for being its
own "intermediate format" already I think. Going straight to HTML (or
something else) is so much more easier and opens the doors for the 99%
of the developer community who doesn't know docbook, Mallard, or
whatever we use.

> When I was first told of Giraffe about a year ago, it was presented as
> a stop-gap for generating HTML for Python API docs from GIR files.
> Canonical had decided that they needed something quickly and had no
> time to work with us in something that would fit GNOME's needs in the
> longer term. Have just given a look at the code in the Giraffe
> repository [1] and it indeed looks to me like something temporal, the
> shortest line between A and B without regards to other needs that we
> have, namely eventually replacing GTK-Doc and having more than one
> output format.

Let me chime in here, as the guilty party behind giraffe :-)

Indeed, I threw giraffe together because at the time there was no way
to generate docs for introspected languages. There were a few wip
projects around, but after trying I couldn't really get any of them to
work.

It is true that the nature of giraffe was somewhat temporal, but I
must also stress that I took some care to write it in a way that
someone could pick it up and make it a complete solution. So yes, it
is a minimal solution, but not necessarily where the road ends.

Let me also clarify that giraffe certainly supports more than one
output format. Currently it supports C and Python docs in HTML; but
one could easily add any form of output (Mallard, or what ever floats
your boat). Personally I want to add Vala and Seed/Gjs output (in
HTML), but have never gotten around to it.

> You mention reusing Giraffe's GIR parser, there's already a GIR parser
> and an AST in GObject-Introspection that is mature, in use and being
> maintained, why not reuse it and share the maintenance cost?

I looked at the ast in gobject-introspection before starting giraffe.
It didn't look like something that was intended as public API (nor do
I think that would be a good idea). Also it did not look designed for
generating documentation.

Since GIR is a relatively simple XML format I decided to do my own
thing. After all parsing XML in Python is not exactly rocket surgery;
so the maintenance overhead of a multi-purpose public API didn't seem
worthwhile for anyone. This also allowed me to expose a more DOM-like
API tailored specifically for doc generation.

Also - giraffe's AST is also mature and maintained - It's been running
in production for over a year :-)

Cheers,
Mikkel