From 3e1a6a010742fa454ffae0a79565a1ae1890ae35 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Thu, 5 Aug 2021 14:18:12 +0100
Subject: Port the girepository API reference to gi-docgen

We use the introspection data as the source for our documentation.

The gtk-doc project is unmaintained, and parsing our code twice isn't
the best use of our build time.

This might be the chance for getting a better girepository documentation
and introspection data, as well.
---
 docs/reference/girepository.toml.in | 27 +++++++++++++++
 docs/reference/meson.build          | 66 ++++++++++++++++++++-----------------
 docs/reference/urlmap.js            |  9 +++++
 gir/meson.build                     |  4 ++-
 subprojects/.gitignore              |  1 +
 subprojects/gi-docgen.wrap          |  6 ++++
 6 files changed, 82 insertions(+), 31 deletions(-)
 create mode 100644 docs/reference/girepository.toml.in
 create mode 100644 docs/reference/urlmap.js
 create mode 100644 subprojects/gi-docgen.wrap

diff --git a/docs/reference/girepository.toml.in b/docs/reference/girepository.toml.in
new file mode 100644
index 00000000..bdcee96f
--- /dev/null
+++ b/docs/reference/girepository.toml.in
@@ -0,0 +1,27 @@
+[library]
+version = "@version@"
+browse_url = "https://gitlab.gnome.org/GNOME/gobject-introspection/"
+repository_url = "https://gitlab.gnome.org/GNOME/gobject-introspection.git"
+website_url = "https://www.gtk.org"
+authors = "The GObject-Introspection maintainers"
+license = "LGPL-2.1-or-later"
+description = "The GObject introspection repository library"
+dependencies = [ "GLib-2.0", "GObject-2.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/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/gobject-introspection/-/blob/HEAD/"
+
+[extra]
+urlmap = "urlmap.js"
diff --git a/docs/reference/meson.build b/docs/reference/meson.build
index 3d2a5567..379da8b9 100644
--- a/docs/reference/meson.build
+++ b/docs/reference/meson.build
@@ -1,37 +1,43 @@
-gnome = import('gnome')
+gidocgen_dep = dependency('gi-docgen',
+  version: '>= 2021.7',
+  fallback: ['gi-docgen', 'dummy_dep'],
+  required: get_option('gtk_doc'),
+)
 
-version_conf = configuration_data()
-version_conf.set('GI_VERSION', meson.project_version())
+gi_docgen = find_program('gi-docgen', required: get_option('gtk_doc'))
 
-version_xml = configure_file(
-  input: 'version.xml.in',
-  output: 'version.xml',
-  configuration: version_conf,
-)
+docs_dir = get_option('prefix') / get_option('datadir') / 'doc'
 
-ignore_headers = [
-  'cmph',
-  'girnode.h',
-  'girparser.h',
-  'girwriter.h',
-  'girmodule.h',
-  'girepository-private.h',
-]
+toml_conf = configuration_data()
+toml_conf.set('version', meson.project_version())
 
-gnome.gtkdoc('gi',
-  main_xml: 'gi-docs.xml',
-  dependencies: girepo_dep,
-  src_dir: 'girepository',
-  content_files: [
-    'gi-struct-hierarchy.xml',
-  ],
-  scan_args: [
-    '--rebuild-types',
-    '--ignore-headers=' + ' '.join(ignore_headers),
-  ],
-  mkdb_args: [
-    '--name-space=g',
-    '--ignore-files=cmph',
+expand_content_files = []
+
+girepository_toml = configure_file(
+  input: 'girepository.toml.in',
+  output: 'girepository.toml',
+  configuration: toml_conf,
+  install: true,
+  install_dir: docs_dir / 'girepository',
+)
+
+custom_target('girepsitory-doc',
+  input: [girepository_toml, girepository_gir],
+  output: 'girepository',
+  command: [
+    gi_docgen,
+    'generate',
+    '--quiet',
+    '--fatal-warnings',
+    '--add-include-path=@0@'.format(meson.current_build_dir() / '../../gir'),
+    '--config=@INPUT0@',
+    '--output-dir=@OUTPUT@',
+    '--no-namespace-dir',
+    '--content-dir=@0@'.format(meson.current_source_dir()),
+    '@INPUT1@',
   ],
+  depend_files: expand_content_files,
+  build_by_default: true,
   install: true,
+  install_dir: docs_dir,
 )
diff --git a/docs/reference/urlmap.js b/docs/reference/urlmap.js
new file mode 100644
index 00000000..deae96b9
--- /dev/null
+++ b/docs/reference/urlmap.js
@@ -0,0 +1,9 @@
+// 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/' ],
+]
diff --git a/gir/meson.build b/gir/meson.build
index 5d646335..2c0c9a94 100644
--- a/gir/meson.build
+++ b/gir/meson.build
@@ -476,7 +476,7 @@ if dep_type != 'pkgconfig'
   girepository_command += glib_libpaths
 endif
 
-gir_files += custom_target('gir-girepository',
+girepository_gir = custom_target('gir-girepository',
   input: girepo_gir_sources,
   output: 'GIRepository-2.0.gir',
   depends: [gobject_gir, gir_giscanner_pymod, girepo_lib],
@@ -494,6 +494,8 @@ gir_files += custom_target('gir-girepository',
   ]
 )
 
+gir_files += girepository_gir
+
 typelibs = []
 if get_option('gi_cross_binary_wrapper') != ''
     gircompiler_command = [get_option('gi_cross_binary_wrapper'), gircompiler.full_path(), ]
diff --git a/subprojects/.gitignore b/subprojects/.gitignore
index c472ccfb..259ad768 100644
--- a/subprojects/.gitignore
+++ b/subprojects/.gitignore
@@ -1,3 +1,4 @@
+gi-docgen
 glib
 libffi
 proxy-libintl
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
-- 
cgit v1.2.1