From 7a2e93e6f4a1184410769c056d4ee3fbea5aa475 Mon Sep 17 00:00:00 2001 From: Takashi Sakamoto Date: Wed, 16 Mar 2022 09:03:48 +0900 Subject: [PATCH] ctl: migrate to gi-docgen from gtk-doc This commit uses gi-docgen and obsolete gtk-doc. Signed-off-by: Takashi Sakamoto --- .github/workflows/build.yml | 4 +-- README.rst | 6 ++-- doc/ctl/alsactl.toml.in | 34 ++++++++++++++++++++ doc/ctl/meson.build | 27 ++++++++++++++++ doc/ctl/overview.md | 5 +++ doc/ctl/urlmap.js | 4 +++ doc/meson.build | 12 +++++++ doc/reference/ctl/alsactl-docs.xml | 51 ------------------------------ doc/reference/ctl/alsactl.types | 10 ------ doc/reference/ctl/meson.build | 10 ------ doc/reference/meson.build | 4 --- src/ctl/meson.build | 9 +----- 12 files changed, 88 insertions(+), 88 deletions(-) create mode 100644 doc/ctl/alsactl.toml.in create mode 100644 doc/ctl/meson.build create mode 100644 doc/ctl/overview.md create mode 100644 doc/ctl/urlmap.js delete mode 100644 doc/reference/ctl/alsactl-docs.xml delete mode 100644 doc/reference/ctl/alsactl.types delete mode 100644 doc/reference/ctl/meson.build diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index eb37592..0052ac6 100644 --- 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 e305642..b771580 100644 --- a/README.rst +++ b/README.rst @@ -64,7 +64,7 @@ Dependencies * libudev1 * Meson * (optional) PyGObject to execute tests -* (optional) gtk-doc to generate documentation +* (optional) 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 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 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 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 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 ead14c4..0844d19 100644 --- 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 index 9a75c77..0000000 --- a/doc/reference/ctl/alsactl-docs.xml +++ /dev/null @@ -1,51 +0,0 @@ - - - -]> - - - - ALSACtl Reference Manual - This document is for the ALSACtl library, version &version;. - - - - - Introduction - 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. - - - - ALSACtl enumerations - - - - - ALSACtl global methods - - - - - ALSACtl objects - - - - - - - - - - Index of all symbols - - - - - - diff --git a/doc/reference/ctl/alsactl.types b/doc/reference/ctl/alsactl.types deleted file mode 100644 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 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 c068396..fdfd4a3 100644 --- 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 e4fdc49..baa7cd7 100644 --- 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, -) -- 2.47.3