Re: How to use gtk-doc for library.gnome.org (libgo)

[Stefan Kost <ensonic hora-obscura de>]

Hi Goran,

Goran Rakic wrote:
> Hi,
> 
> I am working on library.gnome.org (libgo), location that will present user
> and developer docs for Gnome platform, including API references for
> current and past versions of libraries that are part of it and built with
> gtk-doc. You can find more about libgo in [1].

Yes I know about it and I am really happy that it now got online.

> My main problem is that docs need to be built on web server and I am
> unable to use standard make magic to built API references (as deps does
> not exist on server). I tried to setup sandbox environment where I can get
> source and  tmpl directory, main SGML file, referenced XML files... and
> run gtkdoc-scan, gtkdoc-mkdb and gtkdoc-mkhtml
> but I ran into problems [2].
> 
> Is this possible to do for all modules? It seems to me there are too many
> corner cases to think about. Maybe there is some other way I can fetch
> "something" from CVS and build DocBook file directly on the web server?
>
>
> Or request to have generated DocBook file available in CVS for every
> gtk-doc document is possible? Then it will be much easier to have
> translated API references (using xml2po from gnome-doc-utils) and I will
> be able to present API refs as part of libgo like all other user docs.
>
I think the most feasible way would be to interact with build.gnome.org get
up-to-date docs from there. For released versions I would pull the html-disted
docs from the tarballs. If you could install gtkdoc from svn on the machine, you
could use the new shiny gtkdoc-rebase to correct all links.

> To quote Shaun McCance on this: "This has been a problem for just about
> everybody who's tried to do automated documentation grabbing from CVS.
> It's also going to present a problem for documentation translation and
> other stuff. I really think generated documentation files should just go
> in CVS. It makes life easier."
> 
I don't really share that opinion. Problem is that even small changes in e.g.
the docbook stylesheets would lead to diffs and developers would get conflicts.
There is such problem e.g. with po files (language catalogues).

Ciao
  Stefan

> 
> Goran Rakic
> 
> --
> [1] http://live.gnome.org/GnomeWeb/Library
> [2] For gnome-vfs module, executed commands are in COMMANDS.txt, and
> errors are attached as ERRORS-MKDB.txt and ERRORS-MKHTML.txt
> 
> 
> _______________________________________________
> gtk-doc-list mailing list
> gtk-doc-list gnome org
> http://mail.gnome.org/mailman/listinfo/gtk-doc-list