[libgweather/ebassi/gtk4] Use gi-docgen to generate the API reference

[Emmanuele Bassi <ebassi src gnome org>]

commit 8bb14e0fbc00b150bf5cb53afdd6703d08f146e6
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Tue Oct 12 12:30:40 2021 +0100

    Use gi-docgen to generate the API reference
    
    Gtk-doc is currently unmaintained, and fairly slow.
    
    Gi-docgen uses the introspection data to generate the documentation.

 doc/libgweather-docs.xml     |  47 ----------
 doc/libgweather-sections.txt | 216 -------------------------------------------
 doc/libgweather.toml.in      |  45 +++++++++
 doc/libgweather.types        |   5 -
 doc/meson.build              |  68 +++++++-------
 doc/urlmap.js                |  11 +++
 doc/version.xml.in           |   1 -
 meson.build                  |   4 +-
 subprojects/gi-docgen.wrap   |   6 ++
 9 files changed, 100 insertions(+), 303 deletions(-)
---
diff --git a/doc/libgweather.toml.in b/doc/libgweather.toml.in
new file mode 100644
index 00000000..4199068a
--- /dev/null
+++ b/doc/libgweather.toml.in
@@ -0,0 +1,45 @@
+[library]
+namespace = "GWeather"
+version = "@GWEATHER_VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/libgweather/";
+repository_url = "https://gitlab.gnome.org/GNOME/libgweather.git";
+authors = "The GWeather authors"
+license = "GPL-2.0-or-later"
+description = "Weather data collection"
+dependencies = [ "GObject-2.0", "Gio-2.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."Gio-2.0"]
+  name = "Gio"
+  description = "GObject interfaces and objects"
+  docs_url = "https://docs.gtk.org/gio/";
+
+  [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/libgweather/-/blob/HEAD/";
+
+[extra]
+urlmap_file = "urlmap.js"
+
+[[object]]
+pattern = "DEPRECATED"
+hidden = true
+
+[[object]]
+name = "DEPRECATED_FOR"
+hidden = true
diff --git a/doc/meson.build b/doc/meson.build
index b4b32cd2..6a98ba80 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -1,35 +1,41 @@
-version_conf = configuration_data()
-version_conf.set('LIBGWEATHER_VERSION', meson.project_version())
-configure_file(input: 'version.xml.in', output: 'version.xml', configuration: version_conf)
+if get_option('gtk_doc')
+  dependency('gi-docgen', version: '>= 2021.6',
+    fallback: ['gi-docgen', 'dummy_dep'],
+  )
 
-glib_prefix = dependency('glib-2.0').get_pkgconfig_variable('prefix')
-glib_docpath = glib_prefix / 'share/gtk-doc/html'
+  gidocgen = find_program('gi-docgen', required: get_option('gtk_doc'))
 
-gtk_prefix = dependency('gtk+-3.0').get_pkgconfig_variable('prefix')
-gtk_docpath = gtk_prefix / 'share/gtk-doc/html'
+  gweather_docdir = get_option('datadir') / 'doc'
 
-docpath = datadir / 'gtk-doc/html'
+  toml_conf = configuration_data()
+  toml_conf.set('GWEATHER_VERSION', meson.project_version())
 
-gnome.gtkdoc('libgweather',
-  main_xml: 'libgweather-docs.xml',
-  src_dir: include_directories('../libgweather'),
-  dependencies: libgweather_dep,
-  gobject_typesfile: 'libgweather.types',
-  ignore_headers: [
-    'gweather-enum-types.h',
-    'gweather-parser.h',
-    'gweather-private.h',
-  ],
-  mkdb_args: ['--xml-mode', '--output-format=xml'],
-  scan_args: [
-    '--deprecated-guards="GWEATHER_DISABLE_DEPRECATED"'
-  ],
-  fixxref_args: [
-    '--html-dir=@0@'.format(docpath),
-    '--extra-dir=@0@'.format(glib_docpath / 'glib'),
-    '--extra-dir=@0@'.format(glib_docpath /'gobject'),
-    '--extra-dir=@0@'.format(glib_docpath / 'gio'),
-    '--extra-dir=@0@'.format(gtk_docpath / 'gtk'),
-  ],
-  install: true,
-)
+  gweather_toml = configure_file(
+    input: 'libgweather.toml.in',
+    output: 'libgweather.toml',
+    configuration: toml_conf,
+  )
+
+  gweather_content_files = [
+  ]
+
+  custom_target('libgweather-doc',
+    input: gweather_gir[0],
+    output: 'libgweather-3.0',
+    command: [
+      gidocgen,
+      'generate',
+      '--quiet',
+      '--fatal-warnings',
+      '--config', gweather_toml,
+      '--output-dir=@OUTPUT@',
+      '--no-namespace-dir',
+      '--content-dir=@0@'.format(meson.current_source_dir()),
+      '@INPUT@',
+    ],
+    depend_files: [ gweather_toml, gweather_content_files ],
+    build_by_default: true,
+    install: true,
+    install_dir: gweather_docdir,
+  )
+endif
diff --git a/doc/urlmap.js b/doc/urlmap.js
new file mode 100644
index 00000000..04776e14
--- /dev/null
+++ b/doc/urlmap.js
@@ -0,0 +1,11 @@
+// SPDX-FileCopyrightText: 2021 Emmanuele Bassi
+// SPDX-License-Identifier: GPL-2.0-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/' ],
+    [ 'Gtk', 'https://docs.gtk.org/gtk3/' ],
+    [ 'GdkPixbuf', 'https://docs.gtk.org/gdk-pixbuf/' ],
+]
diff --git a/meson.build b/meson.build
index 5b9189e9..eca7b9d2 100644
--- a/meson.build
+++ b/meson.build
@@ -77,9 +77,7 @@ gen_locations_variant = find_program('build-aux/meson/gen_locations_variant.py')
 subdir('data')
 subdir('libgweather')
 subdir('schemas')
-if get_option('gtk_doc')
-  subdir('doc')
-endif
+subdir('doc')
 subdir('po')
 subdir('po-locations')
 
diff --git a/subprojects/gi-docgen.wrap b/subprojects/gi-docgen.wrap
new file mode 100644
index 00000000..98cd9211
--- /dev/null
+++ b/subprojects/gi-docgen.wrap
@@ -0,0 +1,6 @@
+[wrap-git]
+directory=gi-docgen
+url=https://gitlab.gnome.org/GNOME/gi-docgen.git
+push-url=ssh://git gitlab gnome org:GNOME/gi-docgen.git
+revision=main
+depth=1