ctl: migrate to gi-docgen from gtk-doc

This commit uses gi-docgen and obsolete gtk-doc.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index eb3759279700f1ddfbdd5ff633b031255d535987..0052ac61d784b1145b8b4340a77b9b068d92de1d 100644 (file)
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -15,7 +15,7 @@ jobs:
         dnf -y upgrade
         dnf -y install @development-tools
         dnf -y install meson gobject-introspection-devel systemd-devel
-        dnf -y install gtk-doc python3-gobject
+        dnf -y install gi-docgen python3-gobject
     - name: Initialization for build.
       run: |
         meson --prefix=/tmp. -Ddoc=true -Dwarning_level=3 . build
@@ -53,7 +53,7 @@ jobs:
         sudo lxc exec builder -- su ubuntu -c 'sudo apt-get -y full-upgrade'
         sudo lxc exec builder -- su ubuntu -c 'sudo apt-get install -y git build-essential'
         sudo lxc exec builder -- su ubuntu -c 'sudo apt-get install -y meson ninja-build libglib2.0-dev libudev-dev gobject-introspection libgirepository1.0-dev'
-        sudo lxc exec builder -- su ubuntu -c 'sudo apt-get install -y gtk-doc-tools python3-gi'
+        sudo lxc exec builder -- su ubuntu -c 'sudo apt-get install -y gi-docgen python3-gi'
     - name: Checkout repository.
       uses: actions/checkout@v2
     - name: Generate archive and expand it inner the container.

diff --git a/README.rst b/README.rst
index e3056425bd456304a083b1ffbcfa9be4d45d41c1..b7715806ffa7c3560a2a44626f2bb919d00af423 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -64,7 +64,7 @@ Dependencies
 * libudev1 <https://www.freedesktop.org/wiki/Software/systemd/>
 * Meson <https://mesonbuild.com/>
 * (optional) PyGObject <https://pygobject.readthedocs.io/> to execute tests
-* (optional) gtk-doc <https://www.gtk.org/gtk-doc/> to generate documentation
+* (optional) gi-docgen <https://gnome.pages.gitlab.gnome.org/gi-docgen/> to generate documentation
 
 How to build
 ============
@@ -91,14 +91,14 @@ After installed, C headers for APIs are available and pkg-config returns
 arguments for them. For example ::
 
     $ pkg-config --cflags --libs alsactl
-    -I/usr/include/alsa-gobject -I/usr/include/glib-2.0 -I/usr/lib/x86_64-linux-gnu/glib-2.0/include -lalsactl
+    -I/usr/include/alsa-gobject/ctl -I/usr/include/glib-2.0 -I/usr/lib/x86_64-linux-gnu/glib-2.0/include -lalsactl
 
 Generate documentation ::
 
     $ meson --prefix=xxx -D doc=true . build
     $ cd build
     $ meson install
-    $ xdg-open xxx/share/gtk-doc/html/alsactl/index.html
+    $ xdg-open xxx/share/doc/html/index.html
 
 Design note
 ===========

diff --git a/doc/ctl/alsactl.toml.in b/doc/ctl/alsactl.toml.in
new file mode 100644 (file)
index 0000000..e33c66f
--- /dev/null
+++ b/doc/ctl/alsactl.toml.in
@@ -0,0 +1,34 @@
+[library]
+version = "@VERSION@"
+description = "alsactl"
+authors = "Takashi Sakamoto"
+license = "LGPL-3.0-or-later"
+website_url = "https://alsa-project.github.io/alsa-gobject-docs/alsactl/"
+browse_url = "https://github.com/alsa-project/alsa-gobject"
+repository_url = "https://github.com/alsa-project/alsa-gobject.git"
+
+dependencies = [
+  "GLib-2.0",
+  "GObject-2.0",
+]
+
+[dependencies."GLib-2.0"]
+name = "GLib"
+description = "The base utility library"
+docs_url = "https://docs.gtk.org/glib/"
+
+[dependencies."GObject-2.0"]
+name = "GObject"
+description = "The base type system and object class"
+docs_url = "https://docs.gtk.org/gobject/"
+
+[source-location]
+base_url = "https://github.com/alsa-project/alsa-gobject/blob/master/"
+file_format = "{filename}#L{line}"
+
+[extra]
+content_files = [
+  "overview.md",
+]
+
+urlmap_file = "urlmap.js"

diff --git a/doc/ctl/meson.build b/doc/ctl/meson.build
new file mode 100644 (file)
index 0000000..ecbaf9b
--- /dev/null
+++ b/doc/ctl/meson.build
@@ -0,0 +1,27 @@
+ext_contents = [
+  'overview.md',
+]
+
+doc_toml = configure_file(
+  input: 'alsactl.toml.in',
+  output: 'alsactl.toml',
+  configuration: conf,
+)
+
+custom_target('alsactl-doc',
+  input: [ doc_toml, alsactl_gir[0] ],
+  output: 'alsactl',
+  command: [
+    gidocgen,
+    'generate',
+    '--no-namespace-dir',
+    '--config=@INPUT0@',
+    '--output-dir=@OUTPUT@',
+    '--content-dir=@0@'.format(meson.current_source_dir()),
+    '@INPUT1@',
+  ],
+  depend_files: [ ext_contents ],
+  build_by_default: true,
+  install: true,
+  install_dir: doc_dir,
+)

diff --git a/doc/ctl/overview.md b/doc/ctl/overview.md
new file mode 100644 (file)
index 0000000..0b5f4b9
--- /dev/null
+++ b/doc/ctl/overview.md
@@ -0,0 +1,5 @@
+Title: Overview
+
+This library is designed for applications to manipulate ALSA control character device and operate
+control functionality abstracted as card and element. ALSACtlCard represent the card. It holds
+file descriptor and creates GSource for event dispatching by GLib's GMainContext/GMainLoop.

diff --git a/doc/ctl/urlmap.js b/doc/ctl/urlmap.js
new file mode 100644 (file)
index 0000000..915cb9d
--- /dev/null
+++ b/doc/ctl/urlmap.js
@@ -0,0 +1,4 @@
+baseURLs = [
+    [ 'GLib', 'https://docs.gtk.org/glib/' ],
+    [ 'GObject', 'https://docs.gtk.org/gobject/' ],
+]

diff --git a/doc/meson.build b/doc/meson.build
index ead14c4015d9daf5abd18f8f4c92de4bd6047fad..0844d195a30067c33dbeb9e7c71144a897900ff0 100644 (file)
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -1 +1,13 @@
+conf = configuration_data()
+conf.set('VERSION', meson.project_version())
+
+doc_dir =  join_paths(get_option('datadir'), 'doc', meson.project_name())
+
+dependency('gi-docgen',
+  version: '>= 2021.8',
+  fallback: ['gi-docgen', 'dummy_dep'],
+)
+gidocgen = find_program('gi-docgen')
+
+subdir('ctl')
 subdir('reference')

diff --git a/doc/reference/ctl/alsactl-docs.xml b/doc/reference/ctl/alsactl-docs.xml
deleted file mode 100644 (file)
index 9a75c77..0000000
--- a/doc/reference/ctl/alsactl-docs.xml
+++ /dev/null
@@ -1,51 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-                      "http://www.oasis-open.org/docbook/xml/4.5/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>ALSACtl Reference Manual</title>
-    <releaseinfo>This document is for the ALSACtl library, version &version;.
-    </releaseinfo>
-    </bookinfo>
-
-    <chapter id="introduction">
-        <title>Introduction</title>
-        <para>This library is designed for applications to manipulate ALSA
-        control character device and operate control functionality abstracted
-        as card and element. ALSACtlCard represent the card. It holds file
-        descriptor and creates GSource for event dispatching by GLib's
-        GMainContext/GMainLoop.</para>
-    </chapter>
-
-    <chapter id="alsactl-enumerations">
-        <title>ALSACtl enumerations</title>
-        <xi:include href="xml/alsactl-enum-types.xml"/>
-    </chapter>
-
-    <chapter id="alsactl-global-methods">
-        <title>ALSACtl global methods</title>
-        <xi:include href="xml/query.xml"/>
-    </chapter>
-
-    <chapter id="alsactl-objects">
-        <title>ALSACtl objects</title>
-        <xi:include href="xml/card.xml"/>
-        <xi:include href="xml/card-info.xml"/>
-        <xi:include href="xml/elem-id.xml"/>
-        <xi:include href="xml/elem-info.xml"/>
-        <xi:include href="xml/elem-value.xml"/>
-        <xi:include href="xml/alsactl-sigs-marshal.xml"/>
-    </chapter>
-
-    <index id="index-all">
-        <title>Index of all symbols</title>
-        <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
-    </index>
-
-    <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
-
-</book>

diff --git a/doc/reference/ctl/alsactl.types b/doc/reference/ctl/alsactl.types
deleted file mode 100644 (file)
index 308e978..0000000
--- a/doc/reference/ctl/alsactl.types
+++ /dev/null
@@ -1,10 +0,0 @@
-alsactl_elem_type_get_type
-alsactl_elem_iface_type_get_type
-alsactl_elem_access_flag_get_type
-alsactl_event_type_get_type
-alsactl_elem_event_mask_get_type
-alsactl_card_get_type
-alsactl_card_info_get_type
-alsactl_elem_id_get_type
-alsactl_elem_info_get_type
-alsactl_elem_value_get_type

diff --git a/doc/reference/ctl/meson.build b/doc/reference/ctl/meson.build
deleted file mode 100644 (file)
index 40bf47f..0000000
--- a/doc/reference/ctl/meson.build
+++ /dev/null
@@ -1,10 +0,0 @@
-gnome.gtkdoc('alsactl',
-  src_dir : alsactl_dir,
-  main_xml : 'alsactl-docs.xml',
-  scan_args: [
-    '--ignore-headers=privates.h',
-  ],
-  gobject_typesfile: 'alsactl.types',
-  dependencies: alsactl_dependency,
-  install : true,
-)

diff --git a/doc/reference/meson.build b/doc/reference/meson.build
index c06839628a1dbb124b070b5c7b1fdf273b769354..fdfd4a324407855b014c7187ebaa1d3043b6a2c2 100644 (file)
--- a/doc/reference/meson.build
+++ b/doc/reference/meson.build
@@ -1,13 +1,9 @@
-conf = configuration_data()
-conf.set('VERSION', meson.project_version())
-
 configure_file(
   input : 'version.xml.in',
   output : 'version.xml',
   configuration : conf,
 )
 
-subdir('ctl')
 subdir('timer')
 subdir('seq')
 subdir('hwdep')

diff --git a/src/ctl/meson.build b/src/ctl/meson.build
index e4fdc4901ef653805bdeab9947414b4c2ed438b8..baa7cd75052b9d5ebb28efe8a1f60fce30e75045 100644 (file)
--- a/src/ctl/meson.build
+++ b/src/ctl/meson.build
@@ -109,7 +109,7 @@ pkg.generate(library,
 )
 
 # Generate metadata for gobject introspection.
-gnome.generate_gir(library,
+alsactl_gir = gnome.generate_gir(library,
   sources: enums + marshallers + headers + sources,
   nsversion: '0.0',
   namespace: namespace,
@@ -124,10 +124,3 @@ gnome.generate_gir(library,
   header: 'alsactl.h',
   install: true,
 )
-
-# For documentation of gtk-doc.
-alsactl_dir = include_directories('.')
-alsactl_dependency = declare_dependency(
-  link_with: library,
-  dependencies: dependencies,
-)