Re: API documentation from introspection data
- From: Mikkel Kamstrup Erlandsen <mikkel kamstrup gmail com>
- To: Tomeu Vizoso <tomeu tomeuvizoso net>
- Cc: Shaun McCance <shaunm gnome org>, desktop-devel-list <desktop-devel-list gnome org>
- Subject: Re: API documentation from introspection data
- Date: Wed, 22 Feb 2012 09:25:26 +0100
On 18 February 2012 07:47, Tomeu Vizoso <tomeu tomeuvizoso net> wrote:
> 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  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
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
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 :-)
] [Thread Prev