Port gdk-pixbuf to gi-docgen

Follow in the steps of Pango and GTK.

7 files changed, 176 insertions, 341 deletions

diff --git a/docs/gdk-pixbuf-from-drawables.xml b/docs/gdk-pixbuf-from-drawables.xml
deleted file mode 100644
index 99fe3be07..000000000
--- a/docs/gdk-pixbuf-from-drawables.xml
+++ /dev/null
@@ -1,26 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<refentry id="gdk-pixbuf-gdk-pixbuf-from-drawables">
-<refmeta>
-<refentrytitle>Drawables to Pixbufs</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>GDK-PIXBUF Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Drawables to Pixbufs</refname><refpurpose>Getting parts of a GDK drawable's image data into a pixbuf.</refpurpose>
-</refnamediv>
-
-<refsect1>
-<title>Description</title>
-  <para>
-    The functions to take the image data from a GDK windowing system surface
-    and store them into a GdkPixbuf are provided by GDK; see
-    <ulink url="https://developer.gnome.org/gdk3/stable/gdk3-Pixbufs.html">the
-    GDK documentation</ulink>.
-  </para>
-</refsect1>
-
-</refentry>
diff --git a/docs/gdk-pixbuf-rendering.xml b/docs/gdk-pixbuf-rendering.xml
deleted file mode 100644
index 26c8776cc..000000000
--- a/docs/gdk-pixbuf-rendering.xml
+++ /dev/null
@@ -1,26 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<refentry id="gdk-pixbuf-gdk-pixbuf-rendering">
-<refmeta>
-<refentrytitle>Rendering</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>GDK-PIXBUF Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Rendering</refname><refpurpose>Rendering a pixbuf to a GDK drawable.</refpurpose>
-</refnamediv>
-
-
-<refsect1>
-<title>Description</title>
-  <para>
-    The functions to render pixbufs to GDK drawables are provided by GDK, see
-    the <ulink url="https://developer.gnome.org/gdk3/stable/gdk3-Cairo-Interaction.html">GDK
-    documentation</ulink>.
-  </para>
-</refsect1>
-
-</refentry>
diff --git a/docs/gdk-pixbuf.toml.in b/docs/gdk-pixbuf.toml.in
new file mode 100644
index 000000000..50299e5fd
--- /dev/null
+++ b/docs/gdk-pixbuf.toml.in
@@ -0,0 +1,126 @@
+# SPDX-FileCopyrightText: 2021 GNOME Foundation
+#
+# SPDX-License-Identifier: CC0-1.0
+
+[library]
+name = "gdk-pixbuf"
+version = "@VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/gdk-pixbuf/"
+repository_url = "https://gitlab.gnome.org/GNOME/gdk-pixbuf.git"
+website_url = "https://www.gtk.org"
+authors = "GTK Development Team"
+license = "GPL-2.1-or-later"
+description = "Image loading library"
+dependencies = [ "gobject", "gio" ]
+devhelp = true
+search_index = true
+
+  [dependencies.gobject]
+  name = "GObject"
+  description = "The base type system library"
+  docs_url = "https://developer.gnome.org/gobject/stable"
+
+  [dependencies.gio]
+  name = "GIO"
+  description = "GObject Interfaces and Objects"
+  docs_url = "https://developer.gnome.org/gio/stable"
+
+[theme]
+name = "basic"
+show_index_summary = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/gdk-pixbuf/-/blob/master/"
+
+[extra]
+urlmap_file = "urlmap.js"
+content_images = [
+  'apple-red-1a.png',
+  'apple-red-2c.png',
+  'composite.png',
+  'gnome-gmush-1.png',
+]
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_0_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_2_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_4_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_6_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_8_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_10_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_12_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_14_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_16_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_18_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_20_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_22_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_24_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_26_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_28_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_30_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_32_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_34_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_36_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_38_FOR"
+hidden = true
+
+[[object]]
+name = "PIXBUF_DEPRECATED_IN_2_40_FOR"
+hidden = true
diff --git a/docs/gdk-pixbuf.xml b/docs/gdk-pixbuf.xml
deleted file mode 100644
index efe977bdd..000000000
--- a/docs/gdk-pixbuf.xml
+++ /dev/null
@@ -1,229 +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 % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
-<!ENTITY version SYSTEM "version.xml">
-]>
-<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
-  <bookinfo>
-    <title>GDK-PixBuf Reference Manual</title>
-    <releaseinfo>
-      Version &version;
-      The latest version of this documentation can be found on-line at
-      <ulink role="online-location" url="http://library.gnome.org/devel/gdk-pixbuf/unstable/">http://library.gnome.org/devel/gdk-pixbuf/unstable/</ulink>.
-    </releaseinfo>
-    <authorgroup>
-      <author>
-	<firstname>Federico</firstname>
-	<surname>Mena Quintero</surname>
-	<affiliation>
-	  <address>
-	    <email>federico@gimp.org</email>
-	  </address>
-	</affiliation>
-      </author>
-    </authorgroup>
-
-    <copyright>
-      <year>2000</year>
-      <holder>The Free Software Foundation</holder>
-    </copyright>
-
-    <legalnotice>
-      <para>
-	Permission is granted to copy, distribute and/or modify this
-	document under the terms of the <citetitle>GNU Free
-	Documentation License</citetitle>, Version 1.1 or any later
-	version published by the Free Software Foundation with no
-	Invariant Sections, no Front-Cover Texts, and no Back-Cover
-	Texts. You may obtain a copy of the <citetitle>GNU Free
-	Documentation License</citetitle> from the Free Software
-	Foundation by visiting <ulink type="http"
-	url="http://www.fsf.org">their Web site</ulink> or by writing
-	to:
-
-	<address>
-	  The Free Software Foundation, Inc.,
-	  <street>59 Temple Place</street> - Suite 330,
-	  <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>,
-	  <country>USA</country>
-	</address>
-      </para>
-
-      <para>
-	Many of the names used by companies to distinguish their
-	products and services are claimed as trademarks. Where those
-	names appear in any GNOME documentation, and those trademarks
-	are made aware to the members of the GNOME Documentation
-	Project, the names have been printed in caps or initial caps.
-      </para>
-    </legalnotice>
-  </bookinfo>
-
-  <reference>
-    <title>API Reference</title>
-
-    <partintro>
-      <para>
-	This part presents the class and function reference for the
-	gdk-pixbuf library.  Classes are described together with
-	their methods; individual functions are grouped by functional
-	group.
-      </para>
-    </partintro>
-
-    <xi:include href="xml/initialization_versions.xml" />
-
-    <xi:include href="xml/gdk-pixbuf.xml" />
-    <xi:include href="xml/refcounting.xml" />
-    <xi:include href="xml/file-loading.xml" />
-    <xi:include href="xml/file-saving.xml" />
-    <xi:include href="xml/creating.xml" />
-    <xi:include href="xml/inline.xml" />
-    <xi:include href="xml/scaling.xml" />
-    <xi:include href="xml/util.xml" />
-    <xi:include href="xml/animation.xml" />
-
-    <chapter id="LoadableModules">
-      <title>Loadable modules</title>
-      <xi:include href="xml/module_interface.xml" />
-      <xi:include href="xml/gdk-pixbuf-loader.xml" />
-    </chapter>
-
-    <chapter id="Gdk">
-      <title>GDK integration (deprecated)</title>
-      <xi:include href="xml/gdk-pixbuf-rendering.xml" />
-      <xi:include href="xml/gdk-pixbuf-from-drawables.xml" />
-    </chapter>
-  </reference>
-
-  <reference>
-    <title>Tools Reference</title>
-
-    <partintro>
-      <para>
-	This part presents the tools which are shipped with the gdk-pixbuf library.
-      </para>
-    </partintro>
-
-    <xi:include href="gdk-pixbuf-csource.xml" />
-    <xi:include href="gdk-pixbuf-query-loaders.xml" />
-  </reference>
-
-  <index id="api-index-full">
-    <title>Index of all symbols</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 id="api-index-2-2" role="2.2">
-    <title>Index of new symbols in 2.2</title>
-    <xi:include href="xml/api-index-2.2.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-4" role="2.4">
-    <title>Index of new symbols in 2.4</title>
-    <xi:include href="xml/api-index-2.4.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-6" role="2.6">
-    <title>Index of new symbols in 2.6</title>
-    <xi:include href="xml/api-index-2.6.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-8" role="2.8">
-    <title>Index of new symbols in 2.8</title>
-    <xi:include href="xml/api-index-2.8.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-12" role="2.12">
-    <title>Index of new symbols in 2.12</title>
-    <xi:include href="xml/api-index-2.12.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-14" role="2.14">
-    <title>Index of new symbols in 2.14</title>
-    <xi:include href="xml/api-index-2.14.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-18" role="2.18">
-    <title>Index of new symbols in 2.18</title>
-    <xi:include href="xml/api-index-2.18.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-22" role="2.22">
-    <title>Index of new symbols in 2.22</title>
-    <xi:include href="xml/api-index-2.22.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-24" role="2.24">
-    <title>Index of new symbols in 2.24</title>
-    <xi:include href="xml/api-index-2.24.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-26" role="2.26">
-    <title>Index of new symbols in 2.26</title>
-    <xi:include href="xml/api-index-2.26.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-28" role="2.28">
-    <title>Index of new symbols in 2.28</title>
-    <xi:include href="xml/api-index-2.28.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-30" role="2.30">
-    <title>Index of new symbols in 2.30</title>
-    <xi:include href="xml/api-index-2.30.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-32" role="2.32">
-    <title>Index of new symbols in 2.32</title>
-    <xi:include href="xml/api-index-2.32.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-36" role="2.36">
-    <title>Index of new symbols in 2.36</title>
-    <xi:include href="xml/api-index-2.36.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-36-8" role="2.36.8">
-    <title>Index of new symbols in 2.36.8</title>
-    <xi:include href="xml/api-index-2.36.8.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-38" role="2.38">
-    <title>Index of new symbols in 2.38</title>
-    <xi:include href="xml/api-index-2.38.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-2-40" role="2.40">
-    <title>Index of new symbols in 2.40</title>
-    <xi:include href="xml/api-index-2.40.xml"><xi:fallback /></xi:include>
-  </index>
-
-  <!-- License -->
-
-  <appendix id="license">
-    <title>License</title>
-	
-    <para>
-      This library is free software; you can redistribute it and/or
-      modify it under the terms of the <citetitle>GNU Library General
-      Public License</citetitle> as published by the Free Software
-      Foundation; either version 2 of the License, or (at your option)
-      any later version.
-    </para>
-
-    <para>
-      This library is distributed in the hope that it will be useful,
-      but WITHOUT ANY WARRANTY; without even the implied warranty of
-      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-      <citetitle>GNU Library General Public License</citetitle> for
-      more details.
-    </para>
-
-    <para>
-      You may obtain a copy of the <citetitle>GNU Library General
-      Public License</citetitle> from the Free Software Foundation by
-      visiting <ulink type="http" url="http://www.fsf.org">their Web
-      site</ulink> or by writing to:
-
-      <address>
-	Free Software Foundation, Inc.
-	<street>59 Temple Place</street> - Suite 330
-	<city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
-	<country>USA</country>
-      </address>
-    </para>
-  </appendix>
-
-  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
-
-</book>
-
diff --git a/docs/meson.build b/docs/meson.build
index c7c8fe721..d40ba61c0 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -1,69 +1,47 @@
-version_xml = configuration_data()
-version_xml.set('GDK_PIXBUF_VERSION', meson.project_version())
-configure_file(input: 'version.xml.in',
-               output: 'version.xml',
-               configuration: version_xml)
+gidocgen_dep = dependency('gi-docgen',
+  version: '>= 2021.1',
+  fallback: ['gi-docgen', 'dummy_dep'],
+  required: get_option('gtk_doc'),
+)
 
-if gobject_dep.type_name() == 'pkgconfig'
-  glib_prefix = gobject_dep.get_pkgconfig_variable('prefix')
-else
-  glib_prefix = get_option('prefix')
-endif
-glib_docpath = join_paths(glib_prefix, 'share', 'gtk-doc', 'html')
-docpath = join_paths(gdk_pixbuf_datadir, 'gtk-doc', 'html')
 
-private_headers = [
-  'pixops',
-  'gdk-pixbuf.h',
-  'gdk-pixbuf-alias.h',
-  'gdk-pixbuf-autocleanups.h',
-  'gdk-pixbuf-buffer-queue-private.h',
-  'gdk-pixbuf-marshal.h',
-  'gdk-pixbuf-private.h',
-  'gdk-pixbuf-scaled-anim.h',
-  'io-ani-animation.h',
-  'io-gdip-animation.h',
-  'io-gdip-native.h',
-  'io-gdip-propertytags.h',
-  'io-gdip-utils.h',
-  'io-gif-animation.h',
-  'xpm-color-table.h',
-  'test-images.h',
-  'lzw.h',
+toml_conf = configuration_data()
+toml_conf.set('VERSION', meson.project_version())
+toml = configure_file(input: 'gdk-pixbuf.toml.in', output: 'gdk-pixbuf.toml', configuration: toml_conf)
+
+gidocgen = find_program('gi-docgen', required: get_option('gtk_doc'))
+
+docs_dir = gdk_pixbuf_datadir / 'doc/gdk-pixbuf/reference'
+
+expand_content_md_files = [
 ]
 
+build_docs = get_option('gtk_doc')
 if get_option('docs')
-  warning('The "docs" build option is deprecated; please use "gtk_doc=true"')
+  warning('The docs option is deprecated; use -Dgtk_doc=true')
+  build_docs = true
 endif
 
-if get_option('gtk_doc') or get_option('docs')
-  gnome.gtkdoc('gdk-pixbuf',
-               main_xml: 'gdk-pixbuf.xml',
-               src_dir: [ gdk_pixbuf_inc ],
-               dependencies: gdkpixbuf_dep,
-               gobject_typesfile: 'gdk-pixbuf.types',
-               scan_args: [
-                 '--rebuild-types',
-                 '--deprecated-guards="GDK_PIXBUF_ENABLE_BROKEN|GDK_PIXBUF_DISABLE_DEPRECATED"',
-                 '--ignore-headers=' + ' '.join(private_headers),
-               ],
-               fixxref_args: [
-                 '--html-dir=@0@'.format(docpath),
-                 '--extra-dir=@0@'.format(join_paths(glib_docpath, 'glib')),
-                 '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gobject')),
-                 '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gio')),
-               ],
-               html_assets: [
-                 'composite.png',
-               ],
-               content_files: [
-                 'gdk-pixbuf-from-drawables.xml',
-                 'gdk-pixbuf-rendering.xml',
-                 'gdk-pixbuf.xml',
-                 'gdk-pixbuf-csource.xml',
-                 'gdk-pixbuf-query-loaders.xml',
-               ],
-               install: true)
+if build_docs
+  custom_target('gdk-pixbuf-doc',
+    input: [ toml, gdkpixbuf_gir[0] ],
+    output: 'gdk-pixbuf',
+    command: [
+      gidocgen,
+      'generate',
+      '--quiet',
+      '--add-include-path=@0@'.format(meson.current_build_dir() / '../gdk-pixbuf'),
+      '--config=@INPUT0@',
+      '--output-dir=@OUTPUT@',
+      '--no-namespace-dir',
+      '--content-dir=@0@'.format(meson.current_source_dir()),
+      '@INPUT1@',
+    ],
+    depend_files: [ expand_content_md_files ],
+    build_by_default: true,
+    install: true,
+    install_dir: docs_dir,
+  )
 endif
 
 xsltproc = find_program('xsltproc', required: false)
diff --git a/docs/urlmap.js b/docs/urlmap.js
new file mode 100644
index 000000000..eaf2de988
--- /dev/null
+++ b/docs/urlmap.js
@@ -0,0 +1,13 @@
+// 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 = [
+    [ 'Gdk', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4/' ],
+    [ 'GdkWayland', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4-wayland/' ],
+    [ 'GdkX11', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4-x11/' ],
+    [ 'Gsk', 'https://gnome.pages.gitlab.gnome.org/gtk/gsk4/' ],
+    [ 'Gtk', 'https://gnome.pages.gitlab.gnome.org/gtk/gtk4/' ],
+    [ 'Pango', 'https://gnome.pages/gitlab.gnome.org/pango/pango/' ],
+    [ 'PangoCairo', 'https://gnome.pages.gitlab.gnome.org/pango/pangocairo/' ],
+]
diff --git a/docs/version.xml.in b/docs/version.xml.in
deleted file mode 100644
index 90ff08b2b..000000000
--- a/docs/version.xml.in
+++ /dev/null
@@ -1 +0,0 @@
-@GDK_PIXBUF_VERSION@