Merge branch 'bilelmoussaoui/docs' into 'main'

Build & publish docs using gi-docgen

See merge request chergert/libmks!3

.gitlab-ci.yml

@@ -0,0 +1,46 @@
+include:
+  - project: "gnome/citemplates"
+    file: "flatpak/flatpak_ci_initiative.yml"
+
+stages:
+  - test
+  - docs
+  - deploy
+
+flatpak:
+  variables:
+    BUNDLE: "mks-test-widget-dev.flatpak"
+    MANIFEST_PATH: "org.gnome.libmks.mks.json"
+    FLATPAK_MODULE: "mks"
+    RUNTIME_REPO: "https://nightly.gnome.org/gnome-nightly.flatpakrepo"
+    APP_ID: "org.gnome.libmks.mks"
+  extends: ".flatpak"
+
+reference:
+  image: fedora:38
+  stage: docs
+  needs: []
+  variables:
+    MESON_FLAGS: "-Dwerror=true --buildtype=release"
+  before_script:
+    - sudo dnf install -y gtk4-devel meson gcc gi-docgen gobject-introspection-devel
+  script:
+    - mkdir -p pfx/
+    - meson ${MESON_FLAGS} --prefix=${PWD}/pfx -Ddocs=true _build
+    - ninja -C _build install
+    - mkdir -p _reference/
+    - mv pfx/share/doc/libmks1/ _reference/
+  artifacts:
+    paths:
+      - _reference
+
+pages:
+  stage: deploy
+  needs: ["reference"]
+  script:
+    - mv _reference public/
+  artifacts:
+    paths:
+      - public
+  only:
+    - main

docs/Mks.toml.in

@@ -0,0 +1,52 @@
+[library]
+version = "@version@"
+browse_url = "https://gitlab.gnome.org/chergert/libmks"
+repository_url = "https://gitlab.gnome.org/chergert/libmks.git"
+website_url = "https://gitlab.gnome.org/chergert/libmks"
+docs_url = "https://chergert.pages.gitlab.gnome.org/libmks/"
+authors = "Christian Hergert"
+license = "LGPL-2.1-or-later"
+description = "Mouse, Keyboard, and Screen to Qemu"
+dependencies = [ "GObject-2.0", "Gdk-4.0", "Gtk-4.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."GLib-2.0"]
+  name = "GLib"
+  description = "The base type system library"
+  docs_url = "https://docs.gtk.org/glib/"
+
+  [dependencies."Gio-2.0"]
+  name = "Gio"
+  description = "GObject Interfaces and Objects, Networking, IPC, and I/O"
+  docs_url = "https://docs.gtk.org/gio/"
+
+  [dependencies."Gdk-4.0"]
+  name = "Gdk"
+  description = "The GTK windowing system abstraction"
+  docs_url = "https://docs.gtk.org/gdk4/"
+
+  [dependencies."Gtk-4.0"]
+  name = "Gtk"
+  description = "The GTK toolkit"
+  docs_url = "https://docs.gtk.org/gtk4/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/chergert/libmks/-/blob/main/"
+
+[extra]
+content_files = [
+]
+
+urlmap_file = "urlmap.js"
+

docs/meson.build

@@ -0,0 +1,42 @@
+toml_conf = configuration_data()
+toml_conf.set('version', meson.project_version())
+
+gidocgen = find_program('gi-docgen')
+
+gidocgen_common_args = [
+  '--quiet',
+  '--no-namespace-dir',
+]
+
+if get_option('werror')
+  gidocgen_common_args += ['--fatal-warnings']
+endif
+
+docs_dir = get_option('datadir') / 'doc'
+
+if get_option('docs')
+  source_toml = configure_file(
+    input: 'Mks.toml.in',
+    output: 'Mks.toml',
+    configuration: toml_conf,
+    install: true,
+    install_dir: docs_dir / 'libmks1',
+  )
+
+  custom_target('mks-doc',
+    input: [ source_toml, libmks_gir[0] ],
+    output: 'libmks1',
+    command: [
+      gidocgen,
+      'generate',
+      gidocgen_common_args,
+      '--config=@INPUT0@',
+      '--output-dir=@OUTPUT@',
+      '--content-dir=@0@'.format(meson.current_source_dir()),
+      '@INPUT1@',
+    ],
+    build_by_default: true,
+    install: true,
+    install_dir: docs_dir,
+  )
+endif

docs/urlmap.js

@@ -0,0 +1,8 @@
+baseURLs = [
+    [ 'GLib', 'https://docs.gtk.org/glib/' ],
+    [ 'GObject', 'https://docs.gtk.org/gobject/' ],
+    [ 'Gio', 'https://docs.gtk.org/gio/' ],
+    [ 'Gdk', 'https://docs.gtk.org/gdk4/' ],
+    [ 'Gsk', 'https://docs.gtk.org/gsk4/' ],
+    [ 'Gtk', 'https://docs.gtk.org/gtk4/' ],
+]

lib/meson.build

@@ -121,12 +121,14 @@ pkg.generate(
   install_dir: join_paths(get_option('libdir'), 'pkgconfig')
 )
 
-libmks_gir = gnome.generate_gir(libmks,
-              sources: libmks_sources + libmks_headers,
-            nsversion: api_version,
-            namespace: 'Mks',
-        symbol_prefix: 'mks',
-    identifier_prefix: 'Mks',
-             includes: ['Gio-2.0', 'Gtk-4.0'],
-              install: true,
-)
+if get_option('introspection').allowed()
+  libmks_gir = gnome.generate_gir(libmks,
+                sources: libmks_sources + libmks_headers,
+              nsversion: api_version,
+              namespace: 'Mks',
+          symbol_prefix: 'mks',
+      identifier_prefix: 'Mks',
+              includes: ['Gio-2.0', 'Gtk-4.0'],
+                install: true,
+  )
+endif

meson.build

@@ -155,4 +155,8 @@ add_project_link_arguments(project_link_args, language: 'c')
 subdir('lib')
 subdir('tools')
 
+if get_option('docs') and get_option('introspection').allowed()
+  subdir('docs')
+endif
+
 configure_file(output: 'config.h', configuration: config_h)

meson_options.txt

@@ -1 +1,9 @@
 option('install-tools', type: 'boolean', value: false)
+
+option('docs',
+       type: 'boolean', value: false,
+       description: 'Build reference manual')
+
+option('introspection',
+       type: 'feature', value: 'auto',
+       description: 'Generate gir data')