Skip to content

Drop gtk-doc as the API reference generator

From: #3035 (comment 1774436)

Let's break down this in steps:

Preparation

  • remove the existing gtk-doc build of the API references for glib, gobject, and gio
  • move the SECTION docblocks that are not tied to a type to a separate Markdown file under doc/reference
  • move the Markdown files from the docs.gtk.org website into the GLib repository
    • partially done as !3591 (merged)
    • remaining work as !3758 (merged) and gtk!6663 (merged)
    • files in the GTK repository now need to be checked against what landed in GLib (to ensure no intermediate updates were missed) and then deleted
  • port the remaining XML docs into Markdown
  • port the man pages to reStructuredText and use rst2man consistently: !3775 (merged)
  • use the Markdown generator for the gdbus examples
    • Decided to drop them instead, in commit e2efafb8
  • ensure that Unix- and win32-specific APIs (such as GWin32InputStream) are represented correctly in GIR so they can be documented and linked to, regardless of what the docs build platform is
  • ensure gdbus-codegen can output in gi-docgen format as well as gtk-doc format

Switch time

  • port the content of the docblocks from gtk-doc to gi-docgen
    • use gi-docgen links
    • use proper code blocks (with syntax highlighting)
    • ensure that every indented Markdown line is using 2 spaces to avoid being identified as a pre-formatted block
    • in general, follow the style guidelines for developer documentation
    • !3801 (merged)
    • Split out as #3250 because it’s going to take a while and I’m certainly not going to do it all
  • if gobject-introspection is available, generate the introspection data for GLib, GObject, GModule, and GIO when building the libraries
  • if gi-docgen is available and the introspection has been generated, generate the API references from the introspection data and ancillary contents

Since g-i depends on GLib, this means that building the documentation for GLib will need a second build:

  1. build glib with no documentation
  2. build gobject-introspection
  3. build glib with documentation

Side effect: since g-i is tied to GLib due to it containing the introspection data for GLib, by moving the introspection build to GLib itself we can decouple g-i; this should make it easier to build GLib with an older version of gobject-introspection.

Cleaning up

Edited by Philip Withnall