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.

9 files changed, 100 insertions, 303 deletions

diff --git a/doc/libgweather-docs.xml b/doc/libgweather-docs.xml
deleted file mode 100644
index e0a7f0f..0000000
--- a/doc/libgweather-docs.xml
+++ /dev/null
@@ -1,47 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
-[
-<!ENTITY version SYSTEM "version.xml">
-]>
-
-<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
-  <bookinfo>
-    <title>libgweather Reference Manual</title>
-    <releaseinfo>
-      for libgweather &version;.
-      The latest version of this documentation can be found on-line at
-      <ulink role="online-location" url="https://developer.gnome.org/libgweather/unstable/">https://developer.gnome.org/libgweather/unstable/</ulink>.
-    </releaseinfo>
-  </bookinfo>
-
-  <chapter>
-    <title>libgweather Reference Manual</title>
-    <xi:include href="xml/gweatherlocation.xml"/>
-    <xi:include href="xml/gweathertimezone.xml"/>
-    <xi:include href="xml/gweatherinfo.xml"/>
-    <xi:include href="xml/gweatherlocationentry.xml"/>
-    <xi:include href="xml/gweathertimezonemenu.xml"/>
-    <xi:include href="xml/gweatherversion.xml"/>
-
-  </chapter>
-  <chapter id="object-tree">
-    <title>Object Hierarchy</title>
-     <xi:include href="xml/tree_index.sgml"/>
-  </chapter>
-  <index id="api-index-full">
-    <title>API Index</title>
-    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-deprecated" role="deprecated">
-    <title>Index of deprecated symbols</title>
-    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
-  </index>
-
-  <index role="3.12">
-    <title>Index of new symbols in 3.12</title>
-    <xi:include href="xml/api-index-3.12.xml"><xi:fallback/></xi:include>
-  </index>
-
-  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
-</book>
diff --git a/doc/libgweather-sections.txt b/doc/libgweather-sections.txt
deleted file mode 100644
index f9589d8..0000000
--- a/doc/libgweather-sections.txt
+++ /dev/null
@@ -1,216 +0,0 @@
-<INCLUDE>libgweather/gweather.h</INCLUDE>
-
-<SECTION>
-<FILE>gweathertimezonemenu</FILE>
-<TITLE>GWeatherTimezoneMenu</TITLE>
-GWeatherTimezoneMenu
-gweather_timezone_menu_new
-gweather_timezone_menu_set_tzid
-gweather_timezone_menu_get_tzid
-<SUBSECTION Standard>
-GWeatherTimezoneMenuClass
-GWEATHER_TIMEZONE_MENU
-GWEATHER_IS_TIMEZONE_MENU
-GWEATHER_TYPE_TIMEZONE_MENU
-gweather_timezone_menu_get_type
-GWEATHER_TIMEZONE_MENU_CLASS
-GWEATHER_IS_TIMEZONE_MENU_CLASS
-GWEATHER_TIMEZONE_MENU_GET_CLASS
-</SECTION>
-
-<SECTION>
-<FILE>gweatherlocationentry</FILE>
-<TITLE>GWeatherLocationEntry</TITLE>
-GWeatherLocationEntry
-gweather_location_entry_new
-gweather_location_entry_set_location
-gweather_location_entry_get_location
-gweather_location_entry_has_custom_text
-gweather_location_entry_set_city
-<SUBSECTION Standard>
-GWeatherLocationEntryClass
-GWEATHER_LOCATION_ENTRY
-GWEATHER_IS_LOCATION_ENTRY
-GWEATHER_TYPE_LOCATION_ENTRY
-gweather_location_entry_get_type
-GWEATHER_LOCATION_ENTRY_CLASS
-GWEATHER_IS_LOCATION_ENTRY_CLASS
-GWEATHER_LOCATION_ENTRY_GET_CLASS
-GWeatherLocationEntryPrivate
-</SECTION>
-
-<SECTION>
-<FILE>gweatherlocation</FILE>
-<TITLE>GWeatherLocation</TITLE>
-GWeatherLocation
-GWeatherLocationLevel
-gweather_location_get_world
-gweather_location_new_world
-gweather_location_new_detached
-gweather_location_ref
-gweather_location_unref
-
-<SUBSECTION>
-gweather_location_serialize
-gweather_location_deserialize
-gweather_location_equal
-gweather_location_find_by_station_code
-gweather_location_find_nearest_city
-GWeatherFilterFunc
-gweather_location_find_nearest_city_full
-gweather_location_detect_nearest_city
-gweather_location_detect_nearest_city_finish
-
-<SUBSECTION>
-gweather_location_get_level
-gweather_location_level_get_string
-gweather_location_get_parent
-gweather_location_get_children
-
-<SUBSECTION>
-gweather_location_get_name
-gweather_location_get_sort_name
-gweather_location_get_english_name
-gweather_location_has_coords
-gweather_location_get_coords
-gweather_location_get_distance
-gweather_location_get_country
-gweather_location_get_timezone
-gweather_location_get_timezones
-gweather_location_get_code
-gweather_location_get_city_name
-gweather_location_get_country_name
-
-<SUBSECTION Private>
-gweather_location_free_timezones
-
-<SUBSECTION Standard>
-GWEATHER_TYPE_LOCATION
-gweather_location_get_type
-</SECTION>
-
-<SECTION>
-<FILE>gweatherinfo</FILE>
-<TITLE>GWeatherInfo</TITLE>
-
-<SUBSECTION Standard>
-GWeatherInfo
-GWeatherInfoClass
-gweather_info_get_type
-GWEATHER_INFO
-GWEATHER_INFO_CLASS
-GWEATHER_INFO_GET_CLASS
-GWEATHER_IS_INFO
-GWEATHER_IS_INFO_CLASS
-GWEATHER_TYPE_INFO
-GWeatherInfoPrivate
-
-<SUBSECTION>
-gweather_info_new
-gweather_info_update
-gweather_info_abort
-gweather_info_is_valid
-gweather_info_network_error
-gweather_info_store_cache
-gweather_info_get_location
-gweather_info_set_location
-gweather_info_get_forecast
-gweather_info_get_forecast_list
-
-<SUBSECTION>
-GWeatherProvider
-gweather_info_get_enabled_providers
-gweather_info_set_enabled_providers
-gweather_info_get_application_id
-gweather_info_set_application_id
-gweather_info_get_attribution
-
-<SUBSECTION>
-gweather_info_get_location_name
-gweather_info_get_icon_name
-gweather_info_get_symbolic_icon_name
-gweather_info_get_weather_summary
-gweather_info_get_temp_summary
-gweather_info_get_update
-gweather_info_get_sky
-gweather_info_get_conditions
-gweather_info_get_temp
-gweather_info_get_temp_min
-gweather_info_get_temp_max
-gweather_info_get_dew
-gweather_info_get_humidity
-gweather_info_get_wind
-gweather_info_get_pressure
-gweather_info_get_visibility
-gweather_info_get_apparent
-gweather_info_get_sunrise
-gweather_info_get_sunset
-gweather_info_get_radar
-
-<SUBSECTION>
-GWeatherConditionPhenomenon
-GWeatherConditionQualifier
-GWeatherConditions
-gweather_conditions_to_string
-GWeatherSky
-gweather_sky_to_string
-GWeatherWindDirection
-gweather_wind_direction_to_string
-GWeatherMoonLatitude
-GWeatherMoonPhase
-GWeatherDistanceUnit
-GWeatherPressureUnit
-GWeatherSpeedUnit
-gweather_speed_unit_to_string
-GWeatherTemperatureUnit
-
-<SUBSECTION>
-gweather_info_get_value_update
-gweather_info_get_value_sky
-gweather_info_get_value_conditions
-gweather_info_get_value_temp
-gweather_info_get_value_temp_min
-gweather_info_get_value_temp_max
-gweather_info_get_value_dew
-gweather_info_get_value_apparent
-gweather_info_get_value_wind
-gweather_info_get_value_pressure
-gweather_info_get_value_visibility
-gweather_info_get_value_sunrise
-gweather_info_get_value_sunset
-gweather_info_next_sun_event
-gweather_info_get_value_moonphase
-gweather_info_get_upcoming_moonphases
-gweather_info_is_daytime
-</SECTION>
-
-<SECTION>
-<FILE>gweathertimezone</FILE>
-GWeatherTimezone
-gweather_timezone_get_type
-GWEATHER_TYPE_TIMEZONE
-gweather_timezone_get_name
-gweather_timezone_get_tzid
-gweather_timezone_get_by_tzid
-gweather_timezone_get_offset
-gweather_timezone_has_dst
-gweather_timezone_get_dst_offset
-gweather_timezone_ref
-gweather_timezone_unref
-gweather_timezone_get_utc
-</SECTION>
-
-<SECTION>
-<FILE>gweatherversion</FILE>
-<TITLE>Versioning information</TITLE>
-GWEATHER_MAJOR_VERSION
-GWEATHER_MINOR_VERSION
-GWEATHER_MICRO_VERSION
-
-<SUBSECTION>
-GWEATHER_VERSION
-GWEATHER_VERSION_HEX
-
-<SUBSECTION>
-GWEATHER_CHECK_VERSION
-</SECTION>
diff --git a/doc/libgweather.toml.in b/doc/libgweather.toml.in
new file mode 100644
index 0000000..4199068
--- /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/libgweather.types b/doc/libgweather.types
deleted file mode 100644
index 00a899b..0000000
--- a/doc/libgweather.types
+++ /dev/null
@@ -1,5 +0,0 @@
-gweather_location_entry_get_type
-gweather_location_get_type
-gweather_timezone_get_type
-gweather_timezone_menu_get_type
-gweather_info_get_type
\ No newline at end of file
diff --git a/doc/meson.build b/doc/meson.build
index b4b32cd..6a98ba8 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 0000000..04776e1
--- /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/doc/version.xml.in b/doc/version.xml.in
deleted file mode 100644
index 9002026..0000000
--- a/doc/version.xml.in
+++ /dev/null
@@ -1 +0,0 @@
-@LIBGWEATHER_VERSION@
diff --git a/meson.build b/meson.build
index 5b9189e..eca7b9d 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 0000000..98cd921
--- /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