Gtk-Doc generates api reference for the c libraries only right now. We'd like to support generating docs for language bindings too.

Some attempts + discussion can be found in bug #625494: Add DocBook Generator.

Gtk-Doc generates the docbook in gtkdoc-mkdb. Right now it is one set of docbook-xml files (in xml-subdir) for C-docs which gtkdoc-mkhtml/mkpdf transform to html/pdf. The gtkdoc-mkdb file could be extended to output docbook-xml sets for other languages too. We need to figure/add a few think outline in the next sections.

Options

We need an extra option to gtkdoc-mkdb to request the languages (c always on?). E.g. gtkdoc-mkdb could grow a --bindings=abc,def,ghi option to select extra bindings to generate docbook for.

Makefiles

The gtk-doc.mak Makefile snippets would need to loop over all the subdirs for each of the bindings. This will unfortunately also make the builds even slower :/ Options are to improve xsltproc (difficult) or drop using docbook xml + xslt and generate html directly (like doxygen does). The later option would unfortunately kill generating pdf + manpage the way we do now.

Builddir naming scheme

We probably need a new dir layout. Old layout:

docs/
  tmpl/ - deprecated
  xml/ - generated docbook xml (sgml is deperated)
  html/ - generated html docs
  abc-docs.xml - master xml doc
  abc.pdf - generated pdf

New layout:

docs/
  c/
    xml/ - generated docbook xml
    html/ - generated html docs
    abc-docs.xml - master xml doc (per language? - nasty)
    abc.pdf - generated pdf
  python/
    xml/ - generated docbook xml
    html/ - generated html docs
    abc-docs.xml - master xml doc (per language? - nasty)
    abc.pdf - generated pdf

Having per language master xml is nasty, but probably needed. The TODO file in gtk-doc and bug #646094: Get rid of the section.txt file has ideas on how to ease the pain though. Also right now many projects have several files to xi:include in their docs dir. Some of the files (e.g. images or a generic introduction might be shareable).

Installdir naming scheme

We can probably be pragmatic - c docs go to /usr/share/gtk-doc/html/gtk/, python docs to /usr/share/gtk-doc/html/gtk-python/ and so on (that is we just append the language to the subdir).

XRef namespace

Right now gtk-doc already has issues with creating unique xml ids for xrefs (we differentiate between the GtkWidget GType and the GtkWidget struct, but not do that for e.g. enums). This whole scheme would need a review to also take the language bindings into account.

current id generation scheme

  • xml-ids have to follow this scheme.

  • gtk-doc uses the symbolname and applies some transformations to adhere to xml specs
  • gtk-doc prefixes the structs for objects with "struct-"

Transforming doc-blobs

The docbook is generated from introspection information (gtkdoc-scan+gtkdoc-scangobj), source-code comments and conventions (about the c-language), we need to extend that for other languages. One question is where to take the doc-blobs from, can we transform most of the c-related comments? do we need per-language overrides.

As a first step it would probably be a good idea to tackle gobject-introspection integration with gtkdoc.

DocumentationProject/GtkDocLanguageBindings (last edited 2011-08-08 09:21:11 by StefanSauer)