docs: Generate the GdkPixdata API reference

Different introspection file, different API reference.

5 files changed, 95 insertions, 31 deletions

diff --git a/docs/gdk-pixdata.toml.in b/docs/gdk-pixdata.toml.in
new file mode 100644
index 000000000..47f37cb25
--- /dev/null
+++ b/docs/gdk-pixdata.toml.in
@@ -0,0 +1,41 @@
+# SPDX-FileCopyrightText: 2021 GNOME Foundation
+#
+# SPDX-License-Identifier: CC0-1.0
+
+[library]
+name = "gdk-pixdata"
+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 = "Inline image data"
+dependencies = [ "gobject", "gio", "gdk-pixbuf" ]
+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"
+
+  [dependencies."gdk-pixbuf"]
+  name = "GdkPixbuf"
+  description = "Image loading library"
+  docs_url = "../gdk-pixbuf/index.html"
+
+[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"
diff --git a/docs/meson.build b/docs/meson.build
index d4c5fe5ea..c9a16a49b 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -7,7 +7,8 @@ gidocgen_dep = dependency('gi-docgen',
 
 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)
+pixbuf_toml = configure_file(input: 'gdk-pixbuf.toml.in', output: 'gdk-pixbuf.toml', configuration: toml_conf)
+pixdata_toml = configure_file(input: 'gdk-pixdata.toml.in', output: 'gdk-pixdata.toml', configuration: toml_conf)
 
 gidocgen = find_program('gi-docgen', required: get_option('gtk_doc'))
 
@@ -25,7 +26,7 @@ endif
 
 if build_docs
   custom_target('gdk-pixbuf-doc',
-    input: [ toml, gdkpixbuf_gir[0] ],
+    input: [ pixbuf_toml, gdkpixbuf_gir[0] ],
     output: 'gdk-pixbuf',
     command: [
       gidocgen,
@@ -43,6 +44,25 @@ if build_docs
     install: true,
     install_dir: docs_dir,
   )
+
+  custom_target('gdk-pixdata-doc',
+    input: [ pixdata_toml, gdkpixdata_gir[0] ],
+    output: 'gdk-pixdata',
+    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@',
+    ],
+    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
index eaf2de988..caaee10f0 100644
--- a/docs/urlmap.js
+++ b/docs/urlmap.js
@@ -10,4 +10,5 @@ baseURLs = [
     [ '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/' ],
+    [ 'GdkPixbuf', 'https://gnome.pages.gitlab.gnome.org/gdk-pixbuf/' ],
 ]
diff --git a/gdk-pixbuf/gdk-pixdata.c b/gdk-pixbuf/gdk-pixdata.c
index df1036a9a..35f90dffc 100644
--- a/gdk-pixbuf/gdk-pixdata.c
+++ b/gdk-pixbuf/gdk-pixdata.c
@@ -23,19 +23,32 @@
 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 
 /**
- * SECTION:inline
- * @Short_description: Functions for inlined pixbuf handling.
- * @Title: Inline data
+ * GdkPixdata:
+ * @magic: magic number. A valid `GdkPixdata` structure must have
+ *   `GDK_PIXBUF_MAGIC_NUMBER` here
+ * @length: less than 1 to disable length checks, otherwise
+ *   `GDK_PIXDATA_HEADER_LENGTH` plus the length of `pixel_data`
+ * @pixdata_type: information about colorspace, sample width and
+ *   encoding, in a `GdkPixdataType`
+ * @rowstride: Distance in bytes between rows
+ * @width: Width of the image in pixels
+ * @height: Height of the image in pixels
+ * @pixel_data: (array) (element-type guint8): `width` x `height`
+ *   pixels, encoded according to `pixdata_type` and `rowstride`
+ *
+ * A pixel buffer suitable for serialization and streaming.
  * 
- * Using #GdkPixdata, images can be compiled into an application,
+ * Using `GdkPixdata`, images can be compiled into an application,
  * making it unnecessary to refer to external image files at runtime.
- * GdkPixBuf includes a utility named gdk-pixbuf-csource, which
- * can be used to convert image files into #GdkPixdata structures suitable
- * for inclusion in C sources. To convert the #GdkPixdata structures back 
- * into #GdkPixbufs, use gdk_pixbuf_from_pixdata.
  *
- * #GdkPixdata should not be used any more. #GResource should be used to save
- * the original compressed images inside the program's binary.
+ * `GdkPixbuf` includes a utility named `gdk-pixbuf-csource`, which
+ * can be used to convert image files into `GdkPixdata` structures suitable
+ * for inclusion in C sources. To convert the `GdkPixdata` structures back
+ * into a `GdkPixbuf`, use `gdk_pixbuf_from_pixdata()`.
+ *
+ * Deprecated: 2.32: `GdkPixdata` should not be used any more. `GResource`
+ *   should be used to save the original compressed images inside the
+ *   program's binary
  */
 
 #define APPEND g_string_append_printf
diff --git a/gdk-pixbuf/gdk-pixdata.h b/gdk-pixbuf/gdk-pixdata.h
index 0aa2a2550..4c25698a2 100644
--- a/gdk-pixbuf/gdk-pixdata.h
+++ b/gdk-pixbuf/gdk-pixdata.h
@@ -47,7 +47,9 @@ G_BEGIN_DECLS
  *
  * An enumeration containing three sets of flags for a #GdkPixdata struct: 
  * one for the used colorspace, one for the width of the samples and one 
- * for the encoding of the pixel data.  
+ * for the encoding of the pixel data.
+ *
+ * Deprecated: 2.32
  **/
 typedef enum
 {
@@ -64,23 +66,6 @@ typedef enum
   GDK_PIXDATA_ENCODING_MASK     = 0x0f << 24
 } GdkPixdataType;
 
-/**
- * GdkPixdata:
- * @magic: magic number. A valid #GdkPixdata structure must have 
- *    #GDK_PIXBUF_MAGIC_NUMBER here.
- * @length: less than 1 to disable length checks, otherwise 
- *    #GDK_PIXDATA_HEADER_LENGTH + length of @pixel_data. 
- * @pixdata_type: information about colorspace, sample width and 
- *    encoding, in a #GdkPixdataType. 
- * @rowstride: Distance in bytes between rows.
- * @width: Width of the image in pixels.
- * @height: Height of the image in pixels.
- * @pixel_data: (array) (element-type guint8): @width x @height pixels, encoded according to @pixdata_type
- *   and @rowstride.
- *
- * A #GdkPixdata contains pixbuf information in a form suitable for 
- * serialization and streaming.
- **/
 typedef struct _GdkPixdata GdkPixdata;
 struct _GdkPixdata
 {
@@ -99,6 +84,8 @@ struct _GdkPixdata
  * GDK_PIXDATA_HEADER_LENGTH:
  *
  * The length of a #GdkPixdata structure without the @pixel_data pointer.
+ *
+ * Deprecated: 2.32
  **/
 #define	GDK_PIXDATA_HEADER_LENGTH	(4 + 4 + 4 + 4 + 4 + 4)
 
@@ -145,7 +132,9 @@ GdkPixbuf*	gdk_pixbuf_from_pixdata	(const GdkPixdata	*pixdata,
  * @GDK_PIXDATA_DUMP_PIXDATA_STREAM, @GDK_PIXDATA_DUMP_PIXDATA_STRUCT
  * and @GDK_PIXDATA_DUMP_MACROS are mutually exclusive, as are
  * @GDK_PIXBUF_DUMP_GTYPES and @GDK_PIXBUF_DUMP_CTYPES. The remaining
- * elements are optional flags that can be freely added. 
+ * elements are optional flags that can be freely added.
+ *
+ * Deprecated: 2.32
  **/
 typedef enum
 {