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

[grakic]

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].

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.

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."


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@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

[Stefan Kost]

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@...
> http://mail.gnome.org/mailman/listinfo/gtk-doc-list

_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

[David Nečas (Yeti)-2]

Goran Rakic wrote:
> 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].

Generally, this can never work, you just cannot perform
GObject inspection if you haven't built the libraries (with
a little tweaking you can inspect binaries built elsewhere
but you still need them).

One you have the DocBook XML, it's selfcontained and you can
build any final output you wish (I do this regularly).

So how to get the XML?  If you have to build on a web server
without dependencies, you depend on someone else building
the XML and putting it somewhere (explicitly).  Why must the
somewhere be the svn repo?

As Stefan wrote, putting generated files there is a recipe
for neverending conflicts if more than one working copy
exists.  So IMO the question should be how to publish the
XML -- that someone still has to generate somewhere else --
when this someone generates it so that the HTML generator
can fetch it.

Yeti

--
http://gwyddion.net/
_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

[Goran Rakić-3]

This message in months old, many things changed from then.

library-web is using generated XML files from released tarballs, and
contains API references just for stable releases.

Support for unstable references (from SVN trunk) can be implemented by
using output of the BuildBot service (as Stefan already suggested) but I
don't think that's high on Frederic's todo list (who is maintaining
library-web now).

gtkdoc-rebase thing can be very useful, but I don't know what's current
state of cross-linking support in Frederic's code.

Cheers,
Goran

_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list