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


gtkdoc-scan --module=gnome-vfs-2.0 --source-dir=libgnomevfs --ignore- headers="...list from Makefile.am..." --deprecated- guards="GNOME_VFS_DISABLE_DEPRECATED"
gtkdoc-mkdb --module=gnome-vfs-2.0 --source-dir=libgnomevfs --main- sgml-file=gnome-vfs-2.0-docs.sgml -sgml-mode --output-format=xml
gtkdoc-mkhtml gnome-vfs-2.0 gnome-vfs-2.0-docs.sgml
ERROR: GnomeVFSJob has multiple definitions
ERROR: GnomeVFSMethod has multiple definitions
ERROR: GnomeVFSMimeSniffBuffer has multiple definitions
ERROR: GnomeVFSTransform has multiple definitions
ERROR: xdg_mime_type_unknown has multiple definitions
File doesn't exist: ./tmpl/gnome-vfs-ace.sgml
File doesn't exist: ./tmpl/gnome-vfs-acl.sgml
File doesn't exist: ./tmpl/gnome-vfs-client.sgml
File doesn't exist: ./tmpl/gnome-vfs-client-call.sgml
Cannot parse structure field "#line 224 "gnome-vfs-metadata.gob"
        GHashTable * strings" at /usr/share/gtk-doc/data/gtkdoc-common.pl line 2 23, <INPUT> line 119.
Cannot parse structure field "#line 225 "gnome-vfs-metadata.gob"
        GHashTable * integers" at /usr/share/gtk-doc/data/gtkdoc-common.pl line 223, <INPUT> line 119.
Cannot parse structure field "#line 228 "gnome-vfs-metadata.gob"
        gboolean keys_loaded" at /usr/share/gtk-doc/data/gtkdoc-common.pl line 2 23, <INPUT> line 119.
Cannot parse structure field "#line 20 "gnome-vfs-metadata-private.h"
}" at /usr/share/gtk-doc/data/gtkdoc-common.pl line 223, <INPUT> line 119.
File doesn't exist: ./tmpl/gnome-vfs-volume-monitor-client.sgml
File doesn't exist: ./tmpl/gnome-vfs-volume-monitor-daemon.sgml
Cannot parse structure field "#ifdef USE_HAL
        LibHalContext *hal_ctx" at /usr/share/gtk-doc/data/gtkdoc-common.pl line  223, <INPUT> line 228.
Cannot parse structure field "#endif
        GList *last_fstab" at /usr/share/gtk-doc/data/gtkdoc-common.pl line 223,  <INPUT> line 228.
File doesn't exist: ./tmpl/gnome-vfs.sgml
File doesn't exist: ./tmpl/gnome-vfs-address.sgml
File doesn't exist: ./tmpl/gnome-vfs-async-job-map.sgml
File doesn't exist: ./tmpl/gnome-vfs-backend.sgml
File doesn't exist: ./tmpl/gnome-vfs-cancellable-ops.sgml
File doesn't exist: ./tmpl/gnome-vfs-cancellation-private.sgml
File doesn't exist: ./tmpl/gnome-vfs-cdrom.sgml
File doesn't exist: ./tmpl/gnome-vfs-configuration.sgml
File doesn't exist: ./tmpl/GNOME_VFS_Daemon.sgml
File doesn't exist: ./tmpl/gnome-vfs-daemon-method.sgml
WARNING: Parameter described in source code comment block but does not exist -
         FUNCTION: gnome_vfs_directory_visit Parameter: text_uri.
WARNING: Parameter described in source code comment block but does not exist -
         USER_FUNCTION: GnomeVFSDirectoryVisitFunc Parameter: user_data.
File doesn't exist: ./tmpl/gnome-vfs-enum-types.sgml
File doesn't exist: ./tmpl/gnome-vfs-filesystem-type.sgml
File doesn't exist: ./tmpl/gnome-vfs-hal-mounts.sgml
File doesn't exist: ./tmpl/gnome-vfs-handle.sgml
File doesn't exist: ./tmpl/gnome-vfs-handle-private.sgml
File doesn't exist: ./tmpl/gnome-vfs-iso9660.sgml
WARNING: Couldn't parse struct field: type[ISODCL(1
WARNING: Couldn't parse struct field: 1)]
WARNING: Couldn't parse struct field: id[ISODCL(2
WARNING: Couldn't parse struct field: 6)]
WARNING: Couldn't parse struct field: version[ISODCL(7
WARNING: Couldn't parse struct field: 7)]
WARNING: Couldn't parse struct field: data[ISODCL(8
WARNING: Couldn't parse struct field: 2048)]
WARNING: Couldn't parse struct field: type                      [ISODCL (  1
WARNING: Couldn't parse struct field:    1)]
WARNING: Couldn't parse struct field: id                                [ISODCL (  2
WARNING: Couldn't parse struct field:    6)]
WARNING: Couldn't parse struct field: version                   [ISODCL (  7
WARNING: Couldn't parse struct field:    7)]
WARNING: Couldn't parse struct field: unused1                   [ISODCL (  8
WARNING: Couldn't parse struct field:    8)]
WARNING: Couldn't parse struct field: system_id                 [ISODCL (  9
WARNING: Couldn't parse struct field:   40)]
WARNING: Couldn't parse struct field: volume_id                 [ISODCL ( 41
WARNING: Couldn't parse struct field:   72)]
WARNING: Couldn't parse struct field: unused2                   [ISODCL ( 73
WARNING: Couldn't parse struct field:   80)]
WARNING: Couldn't parse struct field: volume_space_size         [ISODCL ( 81
WARNING: Couldn't parse struct field:   88)]
WARNING: Couldn't parse struct field: unused3                   [ISODCL ( 89
WARNING: Couldn't parse struct field:  120)]
WARNING: Couldn't parse struct field: volume_set_size           [ISODCL (121
WARNING: Couldn't parse struct field:  124)]
WARNING: Couldn't parse struct field: volume_sequence_number    [ISODCL (125
WARNING: Couldn't parse struct field:  128)]
WARNING: Couldn't parse struct field: logical_block_size                [ISODCL (129
WARNING: Couldn't parse struct field:  132)]
WARNING: Couldn't parse struct field: path_table_size           [ISODCL (133
WARNING: Couldn't parse struct field:  140)]
WARNING: Couldn't parse struct field: type_l_path_table         [ISODCL (141
WARNING: Couldn't parse struct field:  144)]
WARNING: Couldn't parse struct field: opt_type_l_path_table     [ISODCL (145
WARNING: Couldn't parse struct field:  148)]
WARNING: Couldn't parse struct field: type_m_path_table         [ISODCL (149
WARNING: Couldn't parse struct field:  152)]
WARNING: Couldn't parse struct field: opt_type_m_path_table     [ISODCL (153
WARNING: Couldn't parse struct field:  156)]
WARNING: Couldn't parse struct field: root_directory_record     [ISODCL (157
WARNING: Couldn't parse struct field:  190)]
WARNING: Couldn't parse struct field: volume_set_id             [ISODCL (191
WARNING: Couldn't parse struct field:  318)]
WARNING: Couldn't parse struct field: publisher_id              [ISODCL (319
WARNING: Couldn't parse struct field:  446)]
WARNING: Couldn't parse struct field: preparer_id               [ISODCL (447
WARNING: Couldn't parse struct field:  574)]
WARNING: Couldn't parse struct field: application_id            [ISODCL (575
WARNING: Couldn't parse struct field:  702)]
WARNING: Couldn't parse struct field: copyright_file_id         [ISODCL (703
WARNING: Couldn't parse struct field:  739)]
WARNING: Couldn't parse struct field: abstract_file_id          [ISODCL (740
WARNING: Couldn't parse struct field:  776)]
WARNING: Couldn't parse struct field: bibliographic_file_id     [ISODCL (777
WARNING: Couldn't parse struct field:  813)]
WARNING: Couldn't parse struct field: creation_date             [ISODCL (814
WARNING: Couldn't parse struct field:  830)]
WARNING: Couldn't parse struct field: modification_date         [ISODCL (831
WARNING: Couldn't parse struct field:  847)]
WARNING: Couldn't parse struct field: expiration_date           [ISODCL (848
WARNING: Couldn't parse struct field:  864)]
WARNING: Couldn't parse struct field: effective_date            [ISODCL (865
WARNING: Couldn't parse struct field:  881)]
WARNING: Couldn't parse struct field: file_structure_version    [ISODCL (882
WARNING: Couldn't parse struct field:  882)]
WARNING: Couldn't parse struct field: unused4                   [ISODCL (883
WARNING: Couldn't parse struct field:  883)]
WARNING: Couldn't parse struct field: application_data          [ISODCL (884
WARNING: Couldn't parse struct field:  1395)]
WARNING: Couldn't parse struct field: unused5                   [ISODCL (1396
WARNING: Couldn't parse struct field:  2048)]
WARNING: Couldn't parse struct field: length            [ISODCL (1
WARNING: Couldn't parse struct field:  1)]
WARNING: Couldn't parse struct field: ext_attr_length           [ISODCL (2
WARNING: Couldn't parse struct field:  2)]
WARNING: Couldn't parse struct field: extent                    [ISODCL (3
WARNING: Couldn't parse struct field:  10)]
WARNING: Couldn't parse struct field: size                      [ISODCL (11
WARNING: Couldn't parse struct field:  18)]
WARNING: Couldn't parse struct field: date                      [ISODCL (19
WARNING: Couldn't parse struct field:  25)]
WARNING: Couldn't parse struct field: flags                     [ISODCL (26
WARNING: Couldn't parse struct field:  26)]
WARNING: Couldn't parse struct field: file_unit_size            [ISODCL (27
WARNING: Couldn't parse struct field:  27)]
WARNING: Couldn't parse struct field: interleave                        [ISODCL (28
WARNING: Couldn't parse struct field:  28)]
WARNING: Couldn't parse struct field: volume_sequence_number    [ISODCL (29
WARNING: Couldn't parse struct field:  32)]
WARNING: Couldn't parse struct field: name_len          [ISODCL (33
WARNING: Couldn't parse struct field:  33)]
File doesn't exist: ./tmpl/gnome-vfs-job.sgml
Enum declaration 'typedef enum GnomeVFSOpType GnomeVFSOpType;

typedef struct {
        GnomeVFSURI *uri;
        GnomeVFSOpenMode open_mode;
} GnomeVFSOpenOp;
' does not begin with typedef enum {
warning: failed to load external entity "xml/gnome-vfs-result.xml"
gnome-vfs-2.0-docs.sgml:117: parser error : Failure to process entity gnome-vfs-result
    &gnome-vfs-result;
                      ^
gnome-vfs-2.0-docs.sgml:117: parser error : Entity 'gnome-vfs-result' not defined
    &gnome-vfs-result;
                      ^
warning: failed to load external entity "xml/gnome-vfs-uri.xml"
gnome-vfs-2.0-docs.sgml:118: parser error : Failure to process entity gnome-vfs-uri
    &gnome-vfs-uri;
                   ^
gnome-vfs-2.0-docs.sgml:118: parser error : Entity 'gnome-vfs-uri' not defined
    &gnome-vfs-uri;
                   ^
warning: failed to load external entity "xml/gnome-vfs-utils.xml"
gnome-vfs-2.0-docs.sgml:119: parser error : Failure to process entity gnome-vfs-utils
    &gnome-vfs-utils;
                     ^
gnome-vfs-2.0-docs.sgml:119: parser error : Entity 'gnome-vfs-utils' not defined
    &gnome-vfs-utils;
                     ^
warning: failed to load external entity "xml/gnome-vfs-file-size.xml"
gnome-vfs-2.0-docs.sgml:121: parser error : Failure to process entity gnome-vfs-file-size
    &gnome-vfs-file-size;
                         ^
gnome-vfs-2.0-docs.sgml:121: parser error : Entity 'gnome-vfs-file-size' not defined
    &gnome-vfs-file-size;
                         ^
warning: failed to load external entity "xml/gnome-vfs-file-basic-ops.xml"
gnome-vfs-2.0-docs.sgml:126: parser error : Failure to process entity gnome-vfs-file-basic-ops
      &gnome-vfs-file-basic-ops;
                                ^
gnome-vfs-2.0-docs.sgml:126: parser error : Entity 'gnome-vfs-file-basic-ops' not defined
      &gnome-vfs-file-basic-ops;
                                ^
warning: failed to load external entity "xml/gnome-vfs-file-rw-ops.xml"
gnome-vfs-2.0-docs.sgml:127: parser error : Failure to process entity gnome-vfs-file-rw-ops
      &gnome-vfs-file-rw-ops;
                             ^
gnome-vfs-2.0-docs.sgml:127: parser error : Entity 'gnome-vfs-file-rw-ops' not defined
      &gnome-vfs-file-rw-ops;
                             ^
warning: failed to load external entity "xml/gnome-vfs-file-trunc-ops.xml"
gnome-vfs-2.0-docs.sgml:128: parser error : Failure to process entity gnome-vfs-file-trunc-ops
      &gnome-vfs-file-trunc-ops;
                                ^
gnome-vfs-2.0-docs.sgml:128: parser error : Entity 'gnome-vfs-file-trunc-ops' not defined
      &gnome-vfs-file-trunc-ops;
                                ^
warning: failed to load external entity "xml/gnome-vfs-file-info-ops.xml"
gnome-vfs-2.0-docs.sgml:129: parser error : Failure to process entity gnome-vfs-file-info-ops
      &gnome-vfs-file-info-ops;
                               ^
gnome-vfs-2.0-docs.sgml:129: parser error : Entity 'gnome-vfs-file-info-ops' not defined
      &gnome-vfs-file-info-ops;
                               ^
warning: failed to load external entity "xml/gnome-vfs-directory-basic-ops.xml"
gnome-vfs-2.0-docs.sgml:134: parser error : Failure to process entity gnome-vfs-directory-basic-ops
      &gnome-vfs-directory-basic-ops;
                                     ^
gnome-vfs-2.0-docs.sgml:134: parser error : Entity 'gnome-vfs-directory-basic-ops' not defined
      &gnome-vfs-directory-basic-ops;
                                     ^
warning: failed to load external entity "xml/gnome-vfs-directory-list-ops.xml"
gnome-vfs-2.0-docs.sgml:135: parser error : Failure to process entity gnome-vfs-directory-list-ops
      &gnome-vfs-directory-list-ops;
                                    ^
gnome-vfs-2.0-docs.sgml:135: parser error : Entity 'gnome-vfs-directory-list-ops' not defined
      &gnome-vfs-directory-list-ops;
                                    ^
warning: failed to load external entity "xml/gnome-vfs-directory-find-ops.xml"
gnome-vfs-2.0-docs.sgml:136: parser error : Failure to process entity gnome-vfs-directory-find-ops
      &gnome-vfs-directory-find-ops;
                                    ^
gnome-vfs-2.0-docs.sgml:136: parser error : Entity 'gnome-vfs-directory-find-ops' not defined
      &gnome-vfs-directory-find-ops;
                                    ^
warning: failed to load external entity "xml/gnome-vfs-xfer.xml"
gnome-vfs-2.0-docs.sgml:142: parser error : Failure to process entity gnome-vfs-xfer
      &gnome-vfs-xfer;
                      ^
gnome-vfs-2.0-docs.sgml:142: parser error : Entity 'gnome-vfs-xfer' not defined
      &gnome-vfs-xfer;
                      ^
warning: failed to load external entity "xml/gnome-vfs-monitor.xml"
gnome-vfs-2.0-docs.sgml:143: parser error : Failure to process entity gnome-vfs-monitor
      &gnome-vfs-monitor;
                         ^
gnome-vfs-2.0-docs.sgml:143: parser error : Entity 'gnome-vfs-monitor' not defined
      &gnome-vfs-monitor;
                         ^
warning: failed to load external entity "xml/gnome-vfs-file-advanced-ops.xml"
gnome-vfs-2.0-docs.sgml:144: parser error : Failure to process entity gnome-vfs-file-advanced-ops
      &gnome-vfs-file-advanced-ops;
                                   ^
gnome-vfs-2.0-docs.sgml:144: parser error : Entity 'gnome-vfs-file-advanced-ops' not defined
      &gnome-vfs-file-advanced-ops;
                                   ^
warning: failed to load external entity "xml/gnome-vfs-resolve.xml"
gnome-vfs-2.0-docs.sgml:163: parser error : Failure to process entity gnome-vfs-resolve
    &gnome-vfs-resolve;
                       ^
gnome-vfs-2.0-docs.sgml:163: parser error : Entity 'gnome-vfs-resolve' not defined
    &gnome-vfs-resolve;
                       ^
warning: failed to load external entity "xml/gnome-vfs-ssl.xml"
gnome-vfs-2.0-docs.sgml:164: parser error : Failure to process entity gnome-vfs-ssl
    &gnome-vfs-ssl;
                   ^
gnome-vfs-2.0-docs.sgml:164: parser error : Entity 'gnome-vfs-ssl' not defined
    &gnome-vfs-ssl;
                   ^
warning: failed to load external entity "xml/gnome-vfs-socket.xml"
gnome-vfs-2.0-docs.sgml:165: parser error : Failure to process entity gnome-vfs-socket
    &gnome-vfs-socket;
                      ^
gnome-vfs-2.0-docs.sgml:165: parser error : Entity 'gnome-vfs-socket' not defined
    &gnome-vfs-socket;
                      ^
warning: failed to load external entity "xml/gnome-vfs-socket-buffer.xml"
gnome-vfs-2.0-docs.sgml:166: parser error : Failure to process entity gnome-vfs-socket-buffer
    &gnome-vfs-socket-buffer;
                             ^
gnome-vfs-2.0-docs.sgml:166: parser error : Entity 'gnome-vfs-socket-buffer' not defined
    &gnome-vfs-socket-buffer;
                             ^
warning: failed to load external entity "xml/gnome-vfs-mime.xml"
gnome-vfs-2.0-docs.sgml:183: parser error : Failure to process entity gnome-vfs-mime
    &gnome-vfs-mime;
                    ^
gnome-vfs-2.0-docs.sgml:183: parser error : Entity 'gnome-vfs-mime' not defined
    &gnome-vfs-mime;
                    ^
warning: failed to load external entity "xml/gnome-vfs-mime-utils.xml"
gnome-vfs-2.0-docs.sgml:184: parser error : Failure to process entity gnome-vfs-mime-utils
    &gnome-vfs-mime-utils;
                          ^
gnome-vfs-2.0-docs.sgml:184: parser error : Entity 'gnome-vfs-mime-utils' not defined
    &gnome-vfs-mime-utils;
                          ^
warning: failed to load external entity "xml/gnome-vfs-mime-database.xml"
gnome-vfs-2.0-docs.sgml:185: parser error : Failure to process entity gnome-vfs-mime-database
    &gnome-vfs-mime-database;
                             ^
gnome-vfs-2.0-docs.sgml:185: parser error : Entity 'gnome-vfs-mime-database' not defined
    &gnome-vfs-mime-database;
                             ^
warning: failed to load external entity "xml/gnome-vfs-mime-database-deprecated.xml"
gnome-vfs-2.0-docs.sgml:187: parser error : Failure to process entity gnome-vfs-mime-database-deprecated
    &gnome-vfs-mime-database-deprecated;
                                        ^
gnome-vfs-2.0-docs.sgml:187: parser error : Entity 'gnome-vfs-mime-database-deprecated' not defined
    &gnome-vfs-mime-database-deprecated;
                                        ^
warning: failed to load external entity "xml/gnome-vfs-method.xml"
gnome-vfs-2.0-docs.sgml:202: parser error : Failure to process entity gnome-vfs-method
    &gnome-vfs-method;
                      ^
gnome-vfs-2.0-docs.sgml:202: parser error : Entity 'gnome-vfs-method' not defined
    &gnome-vfs-method;
                      ^
warning: failed to load external entity "xml/gnome-vfs-module.xml"
gnome-vfs-2.0-docs.sgml:203: parser error : Failure to process entity gnome-vfs-module
    &gnome-vfs-module;
                      ^
gnome-vfs-2.0-docs.sgml:203: parser error : Entity 'gnome-vfs-module' not defined
    &gnome-vfs-module;
                      ^
warning: failed to load external entity "xml/gnome-vfs-module-shared.xml"
gnome-vfs-2.0-docs.sgml:204: parser error : Failure to process entity gnome-vfs-module-shared
    &gnome-vfs-module-shared;
                             ^
gnome-vfs-2.0-docs.sgml:204: parser error : Entity 'gnome-vfs-module-shared' not defined
    &gnome-vfs-module-shared;
                             ^
warning: failed to load external entity "xml/gnome-vfs-module-callback-module-api.xml"
gnome-vfs-2.0-docs.sgml:205: parser error : Failure to process entity gnome-vfs-module-callback-module-api
    &gnome-vfs-module-callback-module-api;
                                          ^
gnome-vfs-2.0-docs.sgml:205: parser error : Entity 'gnome-vfs-module-callback-module-api' not defined
    &gnome-vfs-module-callback-module-api;
                                          ^
warning: failed to load external entity "xml/gnome-vfs-transform.xml"
gnome-vfs-2.0-docs.sgml:207: parser error : Failure to process entity gnome-vfs-transform
    &gnome-vfs-transform;
                         ^
gnome-vfs-2.0-docs.sgml:207: parser error : Entity 'gnome-vfs-transform' not defined
    &gnome-vfs-transform;
                         ^
warning: failed to load external entity "xml/gnome-vfs-parse-ls.xml"
gnome-vfs-2.0-docs.sgml:208: parser error : Failure to process entity gnome-vfs-parse-ls
    &gnome-vfs-parse-ls;
                        ^
gnome-vfs-2.0-docs.sgml:208: parser error : Entity 'gnome-vfs-parse-ls' not defined
    &gnome-vfs-parse-ls;
                        ^
warning: failed to load external entity "xml/gnome-vfs-standard-callbacks.xml"
gnome-vfs-2.0-docs.sgml:209: parser error : Failure to process entity gnome-vfs-standard-callbacks
    &gnome-vfs-standard-callbacks;
                                  ^
gnome-vfs-2.0-docs.sgml:209: parser error : Entity 'gnome-vfs-standard-callbacks' not defined
    &gnome-vfs-standard-callbacks;
                                  ^
warning: failed to load external entity "xml/gnome-vfs-module-callback.xml"
gnome-vfs-2.0-docs.sgml:210: parser error : Failure to process entity gnome-vfs-module-callback
    &gnome-vfs-module-callback;
                               ^
gnome-vfs-2.0-docs.sgml:210: parser error : Entity 'gnome-vfs-module-callback' not defined
    &gnome-vfs-module-callback;
                               ^
unable to parse gnome-vfs-2.0-docs.sgml
_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list