use GnomeGoals/Template

This is a proposal for improving the gtkdoc based API docs in our platform as a GnomeGoal. GtkDoc got nice features in the last cycles that ease maintainance of docs and improve the usefulness of them. The goal would address GtkDoc versions 1.8, 1.9, ... and for each the new features.

  • general
    • have complete section docs (each toc-entry should have at least short description)
    • move docs from tmpl files to sources, use the migratetmpl.pl script to help (here are details for doing this for Gtk and GLib

    • fix warnings emitted by gtk-doc, since 1.11 warnings are printed in a gcc style and include file and line-number
    • improve the overall document structure, look at the gtkdoc test projects for examples how to use docbook

    • use xi:include instead of entities to include fragments, this makes the build faster (more noticable on bigger reference docs)
  • 1.8
    • use automatic rebuild of types file
  • 1.9
    • add online url (e.g. library.gnome.org) for cross-refs
    • drop using tmpl-files (use gtkdocize --flavour no-tmpl in your autogen.sh), this speeds up the build a bit

    • add doc-check to unit tests
  • 1.10
    • rename <module>-docs.sgml to <module>-docs.xml if it actually is xml

  • 1.11
    • update docbook dtd in <module>-docs.sgml

    • --name-space option in gtkdoc-mkdb for nicer indexes (1.12 has a heuristic for figuring out the namespace itself)
    • xi:include the generated indexes, instead of having empty index tags, this makes docs builds much faster

DocumentationProject/GtkDocGnomeGoal (last edited 2009-12-18 08:48:29 by JavierJardon)