Port from gtkdoc to gi-docgen

Fixes https://github.com/hughsie/libgusb/issues/79

12 files changed, 98 insertions, 139 deletions

diff --git a/contrib/ci/Dockerfile-debian b/contrib/ci/Dockerfile-debian
index 2dfc3fe..41a9f6f 100644
--- a/contrib/ci/Dockerfile-debian
+++ b/contrib/ci/Dockerfile-debian
@@ -1,8 +1,8 @@
-FROM debian:buster
+FROM debian:testing
 
-RUN echo "deb-src http://deb.debian.org/debian/ buster main" >> /etc/apt/sources.list
+RUN echo "deb-src http://deb.debian.org/debian/ testing main" >> /etc/apt/sources.list
 RUN apt-get update -qq
-RUN apt-get install -yq --no-install-recommends meson libjson-glib-dev
+RUN apt-get install -yq --no-install-recommends meson libjson-glib-dev gi-docgen
 RUN apt-get build-dep --allow-unauthenticated -yq libgusb
 
 RUN mkdir /build
diff --git a/contrib/ci/Dockerfile-fedora b/contrib/ci/Dockerfile-fedora
index 00e5e23..1a3c5f7 100644
--- a/contrib/ci/Dockerfile-fedora
+++ b/contrib/ci/Dockerfile-fedora
@@ -1,4 +1,4 @@
-FROM fedora:34
+FROM fedora:37
 
 RUN dnf -y update
 RUN dnf -y install \
@@ -6,12 +6,12 @@ RUN dnf -y install \
 	glib2-devel \
 	json-glib-devel \
 	gobject-introspection-devel \
-	gtk-doc \
+	gi-docgen \
 	libusb1-devel \
 	meson \
 	redhat-rpm-config \
 	rpm-devel \
 	vala-devel \
-	vala-tools
+	vala
 RUN mkdir /build
 WORKDIR /build
diff --git a/contrib/libgusb.spec.in b/contrib/libgusb.spec.in
index 9f5a531..4d4c42c 100644
--- a/contrib/libgusb.spec.in
+++ b/contrib/libgusb.spec.in
@@ -11,7 +11,7 @@ Source0:   http://people.freedesktop.org/~hughsient/releases/%{name}-%{version}.
 BuildRequires: glib2-devel >= 2.38.0
 BuildRequires: json-glib-devel
 BuildRequires: gobject-introspection-devel
-BuildRequires: gtk-doc
+BuildRequires: gi-docgen
 BuildRequires: libusb1-devel >= 1.0.19
 BuildRequires: umockdev-devel
 BuildRequires: meson
@@ -53,7 +53,7 @@ GLib headers and libraries for gusb.
 %{_bindir}/gusbcmd
 %{_libdir}/libgusb.so
 %{_libdir}/pkgconfig/gusb.pc
-%{_datadir}/gtk-doc/html/gusb
+%{_datadir}/doc/libgusb
 %{_datadir}/gir-1.0/GUsb-1.0.gir
 %{_datadir}/vala/vapi/gusb.deps
 %{_datadir}/vala/vapi/gusb.vapi
diff --git a/docs/api/gusb-docs.sgml b/docs/api/gusb-docs.sgml
deleted file mode 100644
index 96505f7..0000000
--- a/docs/api/gusb-docs.sgml
+++ /dev/null
@@ -1,78 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
-               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
-<!ENTITY version SYSTEM "version.xml">
-]>
-<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
-  <bookinfo>
-    <title>GUsb Reference Manual</title>
-    <releaseinfo>
-      for GUsb &version;
-    </releaseinfo>
-    <authorgroup>
-      <author>
-        <firstname>Richard</firstname>
-        <surname>Hughes</surname>
-        <affiliation>
-          <address>
-            <email>richard@hughsie.com</email>
-          </address>
-        </affiliation>
-      </author>
-    </authorgroup>
-    <copyright>
-      <year>2011</year>
-      <holder>Richard Hughes</holder>
-    </copyright>
-  </bookinfo>
-
-  <reference id="specification">
-    <title>GUSB Specification</title>
-    <partintro>
-      <para>
-        GUsb is a GLib wrapper for libusb1.
-      </para>
-      <para>
-        This manual documents features of GUsb.
-      </para>
-    </partintro>
-    <xi:include href="gusb-introduction.xml"/>
-  </reference>
-
-  <reference id="libgusb">
-    <title>libgusb GObject library</title>
-    <partintro>
-      <para>
-        This part documents GObjects used in libgusb.
-      </para>
-    </partintro>
-    <xi:include href="xml/gusb-context.xml"/>
-    <xi:include href="xml/gusb-source.xml"/>
-    <xi:include href="xml/gusb-device.xml"/>
-    <xi:include href="xml/gusb-device-list.xml"/>
-    <xi:include href="xml/gusb-interface.xml"/>
-    <xi:include href="xml/gusb-endpoint.xml"/>
-  </reference>
-
-  <reference id="libgusb-helpers">
-    <title>libgusb glib helpers</title>
-    <partintro>
-      <para>
-        This part documents helper functions in libgusb.
-      </para>
-    </partintro>
-    <xi:include href="xml/gusb-version.xml"/>
-  </reference>
-
-  <reference id="faq">
-    <title>Frequently asked questions</title>
-    <partintro>
-      <para>
-        This part has answers to developer frequently asked questions.
-      </para>
-    </partintro>
-    <xi:include href="gusb-faq.xml"/>
-  </reference>
-
-</book>
-
diff --git a/docs/api/gusb-faq.xml b/docs/api/gusb-faq.xml
deleted file mode 100644
index 755dd87..0000000
--- a/docs/api/gusb-faq.xml
+++ /dev/null
@@ -1,19 +0,0 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
-
-<chapter id="faq">
-  <title>FAQ</title>
-  <para>
-    The following sections explain frequently asked questions from people.
-  </para>
-
-  <sect1 id="faq-why">
-    <title>Why wrap libusb1?</title>
-    <para>
-      libusb1 is a pain in the arse to use in GLib.
-    </para>
-
-  </sect1>
-
-</chapter>
-
diff --git a/docs/api/gusb-introduction.xml b/docs/api/gusb-introduction.xml
deleted file mode 100644
index 7f16b64..0000000
--- a/docs/api/gusb-introduction.xml
+++ /dev/null
@@ -1,15 +0,0 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
-
-<chapter id="introduction">
-  <title>GUSB Introduction</title>
-
-  <sect1 id="introduction-description">
-    <title>Overall Description</title>
-    <para>
-      GUsb is a GLib wrapper for libusb1.
-    </para>
-  </sect1>
-
-</chapter>
-
diff --git a/docs/api/meson.build b/docs/api/meson.build
deleted file mode 100644
index 13002db..0000000
--- a/docs/api/meson.build
+++ /dev/null
@@ -1,15 +0,0 @@
-gusb_version_xml = configure_file(
-  input : 'version.xml.in',
-  output : 'version.xml',
-  configuration : conf,
-)
-
-gnome.gtkdoc(
-  'gusb',
-  src_dir : [
-    gusb_source_dir,
-    gusb_build_dir,
-  ],
-  main_sgml : 'gusb-docs.sgml',
-  install : true
-)
diff --git a/docs/api/version.xml.in b/docs/api/version.xml.in
deleted file mode 100644
index d78bda9..0000000
--- a/docs/api/version.xml.in
+++ /dev/null
@@ -1 +0,0 @@
-@VERSION@
diff --git a/docs/libgusb.toml.in b/docs/libgusb.toml.in
new file mode 100644
index 0000000..90d6181
--- /dev/null
+++ b/docs/libgusb.toml.in
@@ -0,0 +1,38 @@
+[library]
+version = "@version@"
+browse_url = "https://github.com/hughsie/libgusb"
+repository_url = "https://github.com/hughsie/libgusb.git"
+website_url = "https://github.com/hughsie/libgusb"
+authors = "GUsb Development Team"
+license = "LGPL-2.1-or-later"
+description = "GUsb is a GLib wrapper for libusb1"
+dependencies = [
+                "GObject-2.0",
+                "Gio-2.0",
+                "Json-1.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 = "A modern, easy-to-use VFS API"
+  docs_url = "https://docs.gtk.org/gio/"
+
+  [dependencies."Json-1.0"]
+  name = "Json"
+  description = "API for efficient parsing and writing of JSON (JavaScript Object Notation) streams"
+  docs_url = "https://gnome.pages.gitlab.gnome.org/json-glib/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[extra]
+urlmap_file = "urlmap_libgusb.js"
diff --git a/docs/meson.build b/docs/meson.build
index aab4c62..4d8382c 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -1,3 +1,45 @@
-if get_option('docs')
-subdir('api')
+gidocgen_dep = dependency('gi-docgen',
+  version: '>= 2021.1',
+  native: true,
+  required: false,
+)
+gidocgen_app = find_program('gi-docgen')
+
+if gidocgen_dep.found() and gidocgen_app.found() and get_option('introspection')
+  toml_conf = configuration_data()
+  toml_conf.set('version', meson.project_version())
+
+  libgusb_toml = configure_file(
+    input: 'libgusb.toml.in',
+    output: 'libgusb.toml',
+    configuration: toml_conf
+  )
+
+  custom_target('doc-libgusb',
+    input: [
+      libgusb_toml,
+      libgusb_girtarget[0],
+    ],
+    output: 'libgusb',
+    command: [
+      gidocgen_app,
+      'generate',
+      '--quiet',
+      '--add-include-path=@0@'.format(meson.current_build_dir() / '../libgusb'),
+      '--config=@INPUT0@',
+      '--output-dir=@OUTPUT@',
+      '--no-namespace-dir',
+      '--content-dir=@0@'.format(meson.current_source_dir()),
+      '@INPUT1@',
+    ],
+    depends: [
+      libgusb_girtarget[0],
+    ],
+    build_by_default: true,
+    install: true,
+    install_dir: join_paths(datadir, 'doc'),
+  )
+  install_data(['urlmap_libgusb.js'],
+    install_dir: join_paths(datadir, 'doc', 'libgusb')
+  )
 endif
diff --git a/docs/urlmap_libgusb.js b/docs/urlmap_libgusb.js
new file mode 100644
index 0000000..7e7f2cb
--- /dev/null
+++ b/docs/urlmap_libgusb.js
@@ -0,0 +1,4 @@
+baseURLs = [
+	[ 'Gio', 'https://people.gnome.org/~ebassi/docs/_build/Gio/' ],
+	[ 'GObject', 'https://people.gnome.org/~ebassi/docs/_build/GObject/' ],
+]
diff --git a/meson.build b/meson.build
index 1de92c9..ea8969e 100644
--- a/meson.build
+++ b/meson.build
@@ -130,6 +130,7 @@ add_project_arguments('-DGUSB_COMPILATION', language: 'c')
 
 prefix = get_option('prefix')
 bindir = join_paths(prefix, get_option('bindir'))
+datadir = join_paths(prefix, get_option('datadir'))
 
 configure_file(
   output : 'config.h',
@@ -140,4 +141,6 @@ root_incdir = include_directories('.')
 
 subdir('gusb')
 subdir('tools')
-subdir('docs')
+if get_option('docs')
+  subdir('docs')
+endif