documentation: Generate API references with gi-docgen

gtk-doc support was taken out about six years ago, but never replaced.
Add support for the newer gi-docgen, which should hopefully encourage
both C and GJS users of these libraries to improve the reference.

Part-of: <https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/2248>

doc/reference/cally/cally.toml.in

@@ -0,0 +1,39 @@
+[library]
+version = "@version@"
+browse_url = "https://gitlab.gnome.org/GNOME/mutter/"
+repository_url = "https://gitlab.gnome.org/GNOME/mutter.git"
+website_url = "https://blogs.gnome.org/shell-dev/"
+docs_url = "https://docs.gtk.org/"
+authors = "Mutter Development Team"
+license = "GPL-2.0-or-later"
+description = "The Clutter Accessibility Implementation Library"
+dependencies = [ "GObject-2.0", "Atk-1.0" ]
+devhelp = true
+search_index = true
+
+  [dependencies."GObject-2.0"]
+  name = "GObject"
+  description = "The base type system library"
+  docs_url = "https://docs.gtk.org/gobject/"
+
+  [dependencies."Atk-1.0"]
+  name = "Atk"
+  description = "The Accessibility toolkit"
+  docs_url = "https://docs.gtk.org/atk/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/mutter/-/blob/@vcs_tag@/"
+
+[extra]
+# The same order will be used when generating the index
+content_files = [
+]
+content_images = [
+]
+urlmap_file = "urlmap.js"
+

doc/reference/cally/meson.build

@@ -0,0 +1,33 @@
+
+cally_toml = configure_file(
+  input: 'cally.toml.in',
+  output: 'cally.toml',
+  configuration: toml_conf,
+  install: true,
+  install_dir: docs_dir / 'cally',
+)
+
+custom_target('cally-doc',
+  input: [ cally_toml, libmutter_cally_gir[0] ],
+  output: 'cally',
+  command: [
+    gidocgen,
+    'generate',
+    gidocgen_common_args,
+    '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../cogl/cogl'),
+    '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../cogl/cogl-pango'),
+    '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../clutter/clutter'),
+    '--config=@INPUT0@',
+    '--output-dir=@OUTPUT@',
+    '--content-dir=@0@'.format(meson.current_source_dir()),
+    '@INPUT1@',
+  ],
+  depends: [
+    libmutter_cogl_gir[0],
+    libmutter_cogl_pango_gir[0],
+    libmutter_clutter_gir[0],
+  ],
+  build_by_default: true,
+  install: true,
+  install_dir: docs_dir,
+)

doc/reference/cally/urlmap.js

@@ -0,0 +1,15 @@
+// SPDX-FileCopyrightText: 2021 GNOME Foundation
+// SPDX-License-Identifier: LGPL-2.1-or-later
+
+// A map between namespaces and base URLs for their online documentation
+baseURLs = [
+    [ 'GLib', 'https://docs.gtk.org/glib/' ],
+    [ 'GObject', 'https://docs.gtk.org/gobject/' ],
+    [ 'Gio', 'https://docs.gtk.org/gio/' ],
+    [ 'Atk', 'https://docs.gtk.org/atk/' ],
+    [ 'Gdk', 'https://docs.gtk.org/gdk3/' ],
+    [ 'Gtk', 'https://docs.gtk.org/gtk3/' ],
+    [ 'Pango', 'https://docs.gtk.org/Pango/' ],
+    [ 'PangoCairo', 'https://docs.gtk.org/PangoCairo/' ],
+    [ 'GdkPixbuf', 'https://docs.gtk.org/gdk-pixbuf/' ],
+]

doc/reference/clutter/clutter.toml.in

@@ -0,0 +1,44 @@
+[library]
+version = "@version@"
+browse_url = "https://gitlab.gnome.org/GNOME/mutter/"
+repository_url = "https://gitlab.gnome.org/GNOME/mutter.git"
+website_url = "https://blogs.gnome.org/shell-dev/"
+docs_url = "https://docs.gtk.org/"
+authors = "Mutter Development Team"
+license = "GPL-2.0-or-later"
+description = "An OpenGL based 'interactive canvas' library"
+dependencies = [ "GObject-2.0", "cairo-1.0", "Atk-1.0" ]
+devhelp = true
+search_index = true
+
+  [dependencies."GObject-2.0"]
+  name = "GObject"
+  description = "The base type system library"
+  docs_url = "https://docs.gtk.org/gobject/"
+
+  [dependencies."cairo-1.0"]
+  name = "Cairo"
+  description = "A 2D graphics library with support for multiple output devices"
+  docs_url = "https://www.cairographics.org/manual/"
+
+  [dependencies."Atk-1.0"]
+  name = "Atk"
+  description = "The Accessibility toolkit"
+  docs_url = "https://docs.gtk.org/atk/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/mutter/-/blob/@vcs_tag@/"
+
+[extra]
+# The same order will be used when generating the index
+content_files = [
+]
+content_images = [
+]
+urlmap_file = "urlmap.js"
+

doc/reference/clutter/meson.build

@@ -0,0 +1,31 @@
+
+clutter_toml = configure_file(
+  input: 'clutter.toml.in',
+  output: 'clutter.toml',
+  configuration: toml_conf,
+  install: true,
+  install_dir: docs_dir / 'clutter',
+)
+
+custom_target('clutter-doc',
+  input: [ clutter_toml, libmutter_clutter_gir[0] ],
+  output: 'clutter',
+  command: [
+    gidocgen,
+    'generate',
+    gidocgen_common_args,
+    '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../cogl/cogl'),
+    '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../cogl/cogl-pango'),
+    '--config=@INPUT0@',
+    '--output-dir=@OUTPUT@',
+    '--content-dir=@0@'.format(meson.current_source_dir()),
+    '@INPUT1@',
+  ],
+  depends: [
+    libmutter_cogl_pango_gir[0],
+    libmutter_cogl_gir[0],
+  ],
+  build_by_default: true,
+  install: true,
+  install_dir: docs_dir,
+)

doc/reference/clutter/urlmap.js

@@ -0,0 +1,15 @@
+// SPDX-FileCopyrightText: 2021 GNOME Foundation
+// SPDX-License-Identifier: LGPL-2.1-or-later
+
+// A map between namespaces and base URLs for their online documentation
+baseURLs = [
+    [ 'GLib', 'https://docs.gtk.org/glib/' ],
+    [ 'GObject', 'https://docs.gtk.org/gobject/' ],
+    [ 'Gio', 'https://docs.gtk.org/gio/' ],
+    [ 'Atk', 'https://docs.gtk.org/atk/' ],
+    [ 'Gdk', 'https://docs.gtk.org/gdk3/' ],
+    [ 'Gtk', 'https://docs.gtk.org/gtk3/' ],
+    [ 'Pango', 'https://docs.gtk.org/Pango/' ],
+    [ 'PangoCairo', 'https://docs.gtk.org/PangoCairo/' ],
+    [ 'GdkPixbuf', 'https://docs.gtk.org/gdk-pixbuf/' ],
+]

doc/reference/cogl-pango/cogl-pango.toml.in

@@ -0,0 +1,44 @@
+[library]
+version = "@version@"
+browse_url = "https://gitlab.gnome.org/GNOME/mutter/"
+repository_url = "https://gitlab.gnome.org/GNOME/mutter.git"
+website_url = "https://blogs.gnome.org/shell-dev/"
+docs_url = "https://docs.gtk.org/"
+authors = "Mutter Development Team"
+license = "GPL-2.0-or-later"
+description = "A Low Level GPU Graphics and Utilities API"
+dependencies = [ "GObject-2.0", "Pango-1.0", "PangoCairo-1.0" ]
+devhelp = true
+search_index = true
+
+  [dependencies."GObject-2.0"]
+  name = "GObject"
+  description = "The base type system library"
+  docs_url = "https://docs.gtk.org/gobject/"
+
+  [dependencies."Pango-1.0"]
+  name = "Pango"
+  description = "Text shaping and rendering"
+  docs_url = "https://docs.gtk.org/Pango/"
+
+  [dependencies."PangoCairo-1.0"]
+  name = "PangoCairo"
+  description = "Cairo support for Pango"
+  docs_url = "https://docs.gtk.org/PangoCairo/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/mutter/-/blob/@vcs_tag@/"
+
+[extra]
+# The same order will be used when generating the index
+content_files = [
+]
+content_images = [
+]
+urlmap_file = "urlmap.js"
+

doc/reference/cogl-pango/meson.build

@@ -0,0 +1,29 @@
+
+cogl_pango_toml = configure_file(
+  input: 'cogl-pango.toml.in',
+  output: 'cogl-pango.toml',
+  configuration: toml_conf,
+  install: true,
+  install_dir: docs_dir / 'cogl-pango',
+)
+
+custom_target('cogl-pango-doc',
+  input: [ cogl_pango_toml, libmutter_cogl_pango_gir[0] ],
+  output: 'cogl-pango',
+  command: [
+    gidocgen,
+    'generate',
+    gidocgen_common_args,
+    '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../cogl/cogl'),
+    '--config=@INPUT0@',
+    '--output-dir=@OUTPUT@',
+    '--content-dir=@0@'.format(meson.current_source_dir()),
+    '@INPUT1@',
+  ],
+  depends: [
+    libmutter_cogl_gir[0],
+  ],
+  build_by_default: true,
+  install: true,
+  install_dir: docs_dir,
+)

doc/reference/cogl-pango/urlmap.js

@@ -0,0 +1,15 @@
+// SPDX-FileCopyrightText: 2021 GNOME Foundation
+// SPDX-License-Identifier: LGPL-2.1-or-later
+
+// A map between namespaces and base URLs for their online documentation
+baseURLs = [
+    [ 'GLib', 'https://docs.gtk.org/glib/' ],
+    [ 'GObject', 'https://docs.gtk.org/gobject/' ],
+    [ 'Gio', 'https://docs.gtk.org/gio/' ],
+    [ 'Atk', 'https://docs.gtk.org/atk/' ],
+    [ 'Gdk', 'https://docs.gtk.org/gdk3/' ],
+    [ 'Gtk', 'https://docs.gtk.org/gtk3/' ],
+    [ 'Pango', 'https://docs.gtk.org/Pango/' ],
+    [ 'PangoCairo', 'https://docs.gtk.org/PangoCairo/' ],
+    [ 'GdkPixbuf', 'https://docs.gtk.org/gdk-pixbuf/' ],
+]

doc/reference/cogl/cogl.toml.in

@@ -0,0 +1,44 @@
+[library]
+version = "@version@"
+browse_url = "https://gitlab.gnome.org/GNOME/mutter/"
+repository_url = "https://gitlab.gnome.org/GNOME/mutter.git"
+website_url = "https://blogs.gnome.org/shell-dev/"
+docs_url = "https://docs.gtk.org/"
+authors = "Mutter Development Team"
+license = "GPL-2.0-or-later"
+description = "A Low Level GPU Graphics and Utilities API"
+dependencies = [ "GObject-2.0", "Graphene-1.0", "cairo-1.0" ]
+devhelp = true
+search_index = true
+
+  [dependencies."GObject-2.0"]
+  name = "GObject"
+  description = "The base type system library"
+  docs_url = "https://docs.gtk.org/gobject/"
+
+  [dependencies."Graphene-1.0"]
+  name = "Graphene"
+  description = "A thin layer of mathematical types for 3D libraries"
+  docs_url = "https://ebassi.github.io/graphene/docs"
+
+  [dependencies."cairo-1.0"]
+  name = "Cairo"
+  description = "A 2D graphics library with support for multiple output devices"
+  docs_url = "https://www.cairographics.org/manual/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/mutter/-/blob/@vcs_tag@/"
+
+[extra]
+# The same order will be used when generating the index
+content_files = [
+]
+content_images = [
+]
+urlmap_file = "urlmap.js"
+

doc/reference/cogl/meson.build

@@ -0,0 +1,25 @@
+
+cogl_toml = configure_file(
+  input: 'cogl.toml.in',
+  output: 'cogl.toml',
+  configuration: toml_conf,
+  install: true,
+  install_dir: docs_dir / 'cogl',
+)
+
+custom_target('cogl-doc',
+  input: [ cogl_toml, libmutter_cogl_gir[0] ],
+  output: 'cogl',
+  command: [
+    gidocgen,
+    'generate',
+    gidocgen_common_args,
+    '--config=@INPUT0@',
+    '--output-dir=@OUTPUT@',
+    '--content-dir=@0@'.format(meson.current_source_dir()),
+    '@INPUT1@',
+  ],
+  build_by_default: true,
+  install: true,
+  install_dir: docs_dir,
+)

doc/reference/cogl/urlmap.js

@@ -0,0 +1,15 @@
+// SPDX-FileCopyrightText: 2021 GNOME Foundation
+// SPDX-License-Identifier: LGPL-2.1-or-later
+
+// A map between namespaces and base URLs for their online documentation
+baseURLs = [
+    [ 'GLib', 'https://docs.gtk.org/glib/' ],
+    [ 'GObject', 'https://docs.gtk.org/gobject/' ],
+    [ 'Gio', 'https://docs.gtk.org/gio/' ],
+    [ 'Atk', 'https://docs.gtk.org/atk/' ],
+    [ 'Gdk', 'https://docs.gtk.org/gdk3/' ],
+    [ 'Gtk', 'https://docs.gtk.org/gtk3/' ],
+    [ 'Pango', 'https://docs.gtk.org/Pango/' ],
+    [ 'PangoCairo', 'https://docs.gtk.org/PangoCairo/' ],
+    [ 'GdkPixbuf', 'https://docs.gtk.org/gdk-pixbuf/' ],
+]

doc/reference/meson.build

@@ -0,0 +1,27 @@
+if not have_introspection
+  error('API reference requires introspection.')
+endif
+
+
+toml_conf = configuration_data()
+toml_conf.set('version', libmutter_api_version)
+toml_conf.set('vcs_tag', 'main')
+
+gidocgen = find_program('gi-docgen')
+
+gidocgen_common_args = [
+  '--quiet',
+  '--no-namespace-dir',
+]
+
+if get_option('werror')
+  gidocgen_common_args += ['--fatal-warnings']
+endif
+
+docs_dir = pkgdatadir / 'doc'
+
+subdir('cally')
+subdir('clutter')
+subdir('cogl')
+subdir('cogl-pango')
+subdir('meta')

doc/reference/meta/meson.build

@@ -0,0 +1,34 @@
+
+meta_toml = configure_file(
+  input: 'meta.toml.in',
+  output: 'meta.toml',
+  configuration: toml_conf,
+  install: true,
+  install_dir: docs_dir / 'meta',
+)
+
+custom_target('meta-doc',
+  input: [ meta_toml, libmutter_gir[0] ],
+  output: 'meta',
+  command: [
+    gidocgen,
+    'generate',
+    gidocgen_common_args,
+    '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../clutter/clutter'),
+    '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../cogl/cogl'),
+    '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../cogl/cogl-pango'),
+    '--config=@INPUT0@',
+    '--output-dir=@OUTPUT@',
+    '--content-dir=@0@'.format(meson.current_source_dir()),
+    '@INPUT1@',
+  ],
+  depends: [
+    libmutter_clutter_gir[0],
+    libmutter_cally_gir[0],
+    libmutter_cogl_pango_gir[0],
+    libmutter_cogl_gir[0],
+  ],
+  build_by_default: true,
+  install: true,
+  install_dir: docs_dir,
+)

doc/reference/meta/meta.toml.in

@@ -0,0 +1,44 @@
+[library]
+version = "@version@"
+browse_url = "https://gitlab.gnome.org/GNOME/mutter/"
+repository_url = "https://gitlab.gnome.org/GNOME/mutter.git"
+website_url = "https://blogs.gnome.org/shell-dev/"
+docs_url = "https://docs.gtk.org/"
+authors = "Mutter Development Team"
+license = "GPL-2.0-or-later"
+description = "The Mutter display server, window manager and compositor library"
+dependencies = [ "GObject-2.0", "Gdk-3.0", "Gtk-3.0" ]
+devhelp = true
+search_index = true
+
+  [dependencies."GObject-2.0"]
+  name = "GObject"
+  description = "The base type system library"
+  docs_url = "https://docs.gtk.org/gobject/"
+
+  [dependencies."Gdk-3.0"]
+  name = "GDK"
+  description = "The GTK windowing system abstraction"
+  docs_url = "https://docs.gtk.org/gdk3/"
+
+  [dependencies."Gtk-3.0"]
+  name = "GTK"
+  description = "The GTK toolkit"
+  docs_url = "https://docs.gtk.org/gtk3/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/mutter/-/blob/@vcs_tag@/"
+
+[extra]
+# The same order will be used when generating the index
+content_files = [
+]
+content_images = [
+]
+urlmap_file = "urlmap.js"
+

doc/reference/meta/urlmap.js

@@ -0,0 +1,15 @@
+// SPDX-FileCopyrightText: 2021 GNOME Foundation
+// SPDX-License-Identifier: LGPL-2.1-or-later
+
+// A map between namespaces and base URLs for their online documentation
+baseURLs = [
+    [ 'GLib', 'https://docs.gtk.org/glib/' ],
+    [ 'GObject', 'https://docs.gtk.org/gobject/' ],
+    [ 'Gio', 'https://docs.gtk.org/gio/' ],
+    [ 'Atk', 'https://docs.gtk.org/atk/' ],
+    [ 'Gdk', 'https://docs.gtk.org/gdk3/' ],
+    [ 'Gtk', 'https://docs.gtk.org/gtk3/' ],
+    [ 'Pango', 'https://docs.gtk.org/Pango/' ],
+    [ 'PangoCairo', 'https://docs.gtk.org/PangoCairo/' ],
+    [ 'GdkPixbuf', 'https://docs.gtk.org/gdk-pixbuf/' ],
+]

meson.build

@@ -265,6 +265,12 @@ if have_introspection
   ]
 endif
 
+have_documentation = get_option('docs')
+if have_documentation
+  gidocgen_dep = dependency('gi-docgen', version: '>= 2021.1',
+                            fallback: ['gi-docgen', 'dummy_dep'])
+endif
+
 have_tests = get_option('tests')
 have_core_tests = false
 have_cogl_tests = false
@@ -553,6 +559,9 @@ subdir('data')
 subdir('src')
 subdir('po')
 subdir('doc/man')
+if have_documentation
+  subdir('doc/reference')
+endif
 
 meson.add_install_script('meson/meson-postinstall.sh')
 meson.add_dist_script('meson/check-version.py', meson.project_version(), 'NEWS')
@@ -579,6 +588,7 @@ summary('Wacom', have_libwacom, section: 'Options')
 summary('SM', have_sm, section: 'Options')
 summary('Startup notification', have_startup_notification, section: 'Options')
 summary('Introspection', have_introspection, section: 'Options')
+summary('Documentation', have_documentation, section: 'Options')
 summary('Profiler', have_profiler, section: 'Options')
 summary('Xwayland initfd', have_xwayland_initfd, section: 'Options')
 summary('Xwayland listenfd', have_xwayland_listenfd, section: 'Options')

meson_options.txt

@@ -111,6 +111,12 @@ option('introspection',
   description: 'Enable GObject introspection'
 )
 
+option('docs',
+  type: 'boolean',
+  value: false,
+  description: 'Enable gi-docgen documentation'
+)
+
 option('cogl_tests',
   type: 'boolean',
   value: true,