[libpanel: 1/3] docs: add gi-docgen to automatically generate docs

[Christian Hergert <chergert src gnome org>]

commit d23d3b809019666077fa375c5d9ccf26c13229fd
Author: Stephan Vedder <vedder mbits info>
Date:   Wed Jul 20 09:08:31 2022 +0200

    docs: add gi-docgen to automatically generate docs
    
    Generate the docs automatically from the existing gi

 docs/libpanel.toml.in      | 68 ++++++++++++++++++++++++++++++++++++++++++++++
 docs/meson.build           | 42 ++++++++++++++++++++++++++++
 docs/urlmap.js             | 19 +++++++++++++
 meson.build                |  1 +
 meson_options.txt          |  5 ++++
 subprojects/gi-docgen.wrap |  6 ++++
 6 files changed, 141 insertions(+)
---
diff --git a/docs/libpanel.toml.in b/docs/libpanel.toml.in
new file mode 100644
index 0000000..5db40b7
--- /dev/null
+++ b/docs/libpanel.toml.in
@@ -0,0 +1,68 @@
+[library]
+namespace = "libpanel"
+version = "@PANEL_VERSION@"
+browse_url = "https://gitlab.gnome.org/chergert/libpanel";
+repository_url = "https://gitlab.gnome.org/chergert/libpanel.git";
+authors = "Christian Hergert"
+license = "LGPL"
+description = "A dock/panel library for GTK 4"
+dependencies = [ "GObject-2.0", "Libadwaita-1", "Gtk-4.0"]
+devhelp = true
+search_index = true
+
+  [dependencies."GObject-2.0"]
+  name = "GObject"
+  description = "The base type system library"
+  docs_url = "https://developer.gnome.org/gobject/stable";
+
+  [dependencies."Libadwaita-1"]
+  name = "Libadwaita"
+  description = "Building blocks for modern GNOME applications"
+  docs_url = "https://gnome.pages.gitlab.gnome.org/libadwaita/doc/";
+
+  [dependencies."Gtk-4.0"]
+  name = "GTK"
+  description = "The GTK toolkit"
+  docs_url = "https://docs.gtk.org/gtk4/";
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/chergert/libpanel/-/blob/main/";
+
+[extra]
+urlmap_file = "urlmap.js"
+
+[[object]]
+pattern = "DEPRECATED_IN_*"
+hidden = true
+
+[[object]]
+name = "DEPRECATED_FOR"
+hidden = true
+
+[[object]]
+name = "UNAVAILABLE"
+hidden = true
+
+[[object]]
+name = "ParserError"
+  [[object.function]]
+  name = "quark"
+  check_ignore = true
+
+
+[[object]]
+name = "PathError"
+  [[object.function]]
+  name = "quark"
+  check_ignore = true
+
+[[object]]
+name = "ReaderError"
+  [[object.function]]
+  name = "quark"
+  check_ignore = true
diff --git a/docs/meson.build b/docs/meson.build
new file mode 100644
index 0000000..159c4b7
--- /dev/null
+++ b/docs/meson.build
@@ -0,0 +1,42 @@
+if get_option('docs').allowed() and get_option('introspection').allowed() 
+  dependency('gi-docgen', version: '>= 2021.1',
+           fallback: ['gi-docgen', 'dummy_dep'],
+           native: true,
+           required: get_option('docs'))
+
+  gidocgen = find_program('gi-docgen')
+
+  docdir = datadir / 'doc'
+
+  toml_conf = configuration_data()
+  toml_conf.set('PANEL_VERSION', meson.project_version())
+
+  libpanel_toml = configure_file(
+    input: 'libpanel.toml.in',
+    output: 'libpanel.toml',
+    configuration: toml_conf,
+  )
+
+  custom_target('panel-doc',
+    input:  libpanel_gir[0],
+    output: 'panel-1.0',
+    command: [
+      gidocgen,
+      'generate',
+      '--quiet',
+      '--fatal-warnings',
+      '--add-include-path=@0@'.format(meson.current_build_dir() / '../src'),
+      '--config', libpanel_toml,
+      '--output-dir=@OUTPUT@',
+      '--no-namespace-dir',
+      '--content-dir=@0@'.format(meson.current_source_dir()),
+      '@INPUT@',
+    ],
+    depend_files: [ libpanel_toml ],
+    build_by_default: true,
+    install: true,
+    install_dir: docdir,
+  )
+elif get_option('docs').allowed() and get_option('introspection').disabled() 
+  error('docs require introspection')
+endif
diff --git a/docs/urlmap.js b/docs/urlmap.js
new file mode 100644
index 0000000..90a8d6b
--- /dev/null
+++ b/docs/urlmap.js
@@ -0,0 +1,19 @@
+// SPDX-FileCopyrightText: 2021 GNOME Foundation
+// SPDX-License-Identifier: LGPL-2.1-or-later
+
+// Copied from GTK
+
+// A map between namespaces and base URLs for their online documentation
+baseURLs = [
+    [ 'Gdk', 'https://docs.gtk.org/gdk4/' ],
+    [ 'GdkWayland', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4-wayland/' ],
+    [ 'GdkX11', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4-x11/' ],
+    [ 'Gsk', 'https://docs.gtk.org/gsk4/' ],
+    [ 'Gtk', 'https://docs.gtk.org/gtk4/' ],
+    [ 'Pango', 'https://docs.gtk.org/Pango/' ],
+    [ 'PangoCairo', 'https://gnome.pages.gitlab.gnome.org/pango/pangocairo/' ],
+    [ 'GLib', 'https://docs.gtk.org/glib/' ],
+    [ 'Gio', 'https://docs.gtk.org/gio/' ],
+    [ 'GObject', 'https://docs.gtk.org/gobject/' ]
+]
+
diff --git a/meson.build b/meson.build
index 378a86f..953a16d 100644
--- a/meson.build
+++ b/meson.build
@@ -198,5 +198,6 @@ subdir('src')
 subdir('example')
 subdir('testsuite')
 subdir('po')
+subdir('docs')
 
 gnome.post_install(gtk_update_icon_cache: true)
diff --git a/meson_options.txt b/meson_options.txt
index 00f9bf6..d65e72a 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -8,6 +8,11 @@ option('introspection',
        value: 'enabled', 
        description: 'Enable GObject Introspection')
 
+option('docs',
+       type: 'feature', 
+       value: 'auto', yield: true,
+       description: 'Build the API reference (requires gi-docgen)')
+
 option('vapi',
        type: 'boolean', 
        value: true,
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