From 2de9dda6076cdbc835f26715946efdf2d67c358e Mon Sep 17 00:00:00 2001 From: Richard Hughes Date: Thu, 29 Sep 2022 08:44:16 +0100 Subject: Port from gtkdoc to gi-docgen Fixes https://github.com/hughsie/libgusb/issues/79 --- contrib/ci/Dockerfile-debian | 6 ++-- contrib/ci/Dockerfile-fedora | 6 ++-- contrib/libgusb.spec.in | 4 +-- docs/api/gusb-docs.sgml | 78 ------------------------------------------ docs/api/gusb-faq.xml | 19 ---------- docs/api/gusb-introduction.xml | 15 -------- docs/api/meson.build | 15 -------- docs/api/version.xml.in | 1 - docs/libgusb.toml.in | 38 ++++++++++++++++++++ docs/meson.build | 46 +++++++++++++++++++++++-- docs/urlmap_libgusb.js | 4 +++ meson.build | 5 ++- 12 files changed, 98 insertions(+), 139 deletions(-) delete mode 100644 docs/api/gusb-docs.sgml delete mode 100644 docs/api/gusb-faq.xml delete mode 100644 docs/api/gusb-introduction.xml delete mode 100644 docs/api/meson.build delete mode 100644 docs/api/version.xml.in create mode 100644 docs/libgusb.toml.in create mode 100644 docs/urlmap_libgusb.js 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 @@ - - -]> - - - GUsb Reference Manual - - for GUsb &version; - - - - Richard - Hughes - -
- richard@hughsie.com -
- - - - - 2011 - Richard Hughes - - - - - GUSB Specification - - - GUsb is a GLib wrapper for libusb1. - - - This manual documents features of GUsb. - - - - - - - libgusb GObject library - - - This part documents GObjects used in libgusb. - - - - - - - - - - - - libgusb glib helpers - - - This part documents helper functions in libgusb. - - - - - - - Frequently asked questions - - - This part has answers to developer frequently asked questions. - - - - - - - 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 @@ - - - - - FAQ - - The following sections explain frequently asked questions from people. - - - - Why wrap libusb1? - - libusb1 is a pain in the arse to use in GLib. - - - - - - 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 @@ - - - - - GUSB Introduction - - - Overall Description - - GUsb is a GLib wrapper for libusb1. - - - - - 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 -- cgit v1.2.1