Add API reference generation using gi-docgen

CHANGELOG.md

@@ -7,55 +7,33 @@ packaging changes like new dependencies or build system changes.
 Casilda used even/odd minor numbers to differentiate between stable and
 development releases.
 
-## 0.9.2
 
-2025-07-27 - Scrollable Release!
+## Unreleased
 
+ - Add dmabuf support (Val Packett)
+ - Added vapi generation (PaladinDev)
+ - Add library soname (Benson Muite
  - Implement GtkScrollable iface
  - Add casilda_compositor_get_client_socket_fd()
  - Add casilda_compositor_spawn_async()
  - Remove bg-color property
-
-### Issues
-
- - #8 "Investigate using WAYLAND_SOCKET"
- - #7 "Implement GtkScrollable iface"
-
-## Packaging
-
- - API version changed from 0.1 to 0.2 because bg-color property was removed
- - API version will be bumped to 1.0 in next stable release 
-
-## 0.9.0
-
-2025-06-22 - Native rendering Release!
-
- - Fix rendering glitch on resize
- - Do not use wlr scene layout
  - Render windows and popups directly in snapshot()
  - Position windows on center of widget
  - Position transient windows on center of parent
  - Fix unmaximize
 
-### Issues
-
- - #11 "Resource leak causing crash with dmabuf"
- - #3 " Unmaximize not working properly"
-
 ## Packaging
 
+ - API/soname version bumped from 0.1 to 1.0
+ - Small API break (bg-color property was removed)
  - Do not install private header casilda-wayland-source.h 
 
-## 0.3.0
-
-2025-05-27 - Dmabuf Release!
-
- - Add dmabuf support (Val Packett)
- - Added vapi generation (PaladinDev)
- - Add library soname (Benson Muite)
-
 ### Issues
 
+ - #8 "Investigate using WAYLAND_SOCKET"
+ - #7 "Implement GtkScrollable iface"
+ - #11 "Resource leak causing crash with dmabuf"
+ - #3 " Unmaximize not working properly"
  - #2 "Add dmabuff support" (Val Packett)
  - #9 "Bad performance"
  - #10 "Add a soname to shared library" (Benson Muite)

README.md

@@ -31,7 +31,7 @@ Source code lives on GNOME gitlab [here](https://gitlab.gnome.org/jpu/casilda)
 
 This is a regular meson package and can be installed the usual way.
 
-```
+```bash
 # Configure project in _build directory
 meson setup --wipe --prefix=~/.local _build .
 
@@ -42,56 +42,25 @@ ninja -C _build install
 ## How to use it
 
 To add a Wayland compositor to your application all you have to do is create a
-CasildaCompositor widget.
+CasildaCompositor widget and pack it as any other widget.
 
-You can specify which UNIX socket the compositor will listen for clients
+```c
-connections or let it will choose one automatically.
-
-```
-compositor = casilda_compositor_new ("/tmp/casilda-example.sock");
-gtk_window_set_child (GTK_WINDOW (window), GTK_WIDGET (compositor));
-```
-
-Once the compositor is running you can connect to it by specifying the socket
-in WAYLAND_DISPLAY environment variable.
-
-```
-export GDK_BACKEND=wayland
-export WAYLAND_DISPLAY=/tmp/casilda-example.sock
-gtk4-demo
-```
-
-If you do not want any client being able to connect to the compositor you can
-pass NULL as socket and spawn the client with casilda_compositor_spawn_async()
-or get an already connected socket with casilda_compositor_get_client_socket_fd()
-and pass it to the client on WAYLAND_SOCKET env variable.
-
-```
 compositor = casilda_compositor_new (NULL);
 gtk_window_set_child (GTK_WINDOW (window), GTK_WIDGET (compositor));
 gtk_window_present (GTK_WINDOW (window));
+```
 
+The easiest way to show another process window in the compositor is to spawn the
+process using the helper function provided by Casilda
+
+```c
 gchar *argv[] = { "/usr/bin/gtk4-demo", NULL };
 casilda_compositor_spawn_async (compositor, NULL, argv, NULL, G_SPAWN_DEFAULT, NULL, NULL, NULL, NULL);
 ```
 
 ## API
 
-The api is pretty simple CasildaCompositor.
+Casilda uses gi-docgen to generate it API reference documentation
-
-Properties:
-
-- socket: The unix socket file to connect to this compositor (string)
-- scrollable: True to make widget scrollable.
-
-Methods:
-
-- `casilda_compositor_get_client_socket_fd ()`
-  Create a client socket file descriptor connected to this compositor ready to use by passing it to a client with
-  WAYLAND_SOCKET environment variable.
-
-- `casilda_compositor_spawn_async ()`
-  Executes a child program asynchronously with the right environment to automatically connect to this compositor.
 
 ## Contributing
 

docs/casilda.toml.in

@@ -0,0 +1,40 @@
+# SPDX-FileCopyrightText: 2025 Juan Pablo Ugarte
+# SPDX-License-Identifier: CC0-1.0
+
+[library]
+version = "@VERSION@"
+description = "A simple Wayland compositor widget for Gtk 4"
+authors = "Juan Pablo Ugarte"
+license = "LGPL-2.1-only"
+website_url = "https://gitlab.gnome.org/jpu/casilda"
+browse_url = "https://gitlab.gnome.org/jpu/casilda"
+repository_url = "https://gitlab.gnome.org/jpu/casilda.git"
+devhelp = true
+search_index = true
+
+dependencies = [
+  "Gtk-4.0",
+  "GLib-2.0",
+  "GObject-2.0"
+]
+
+[dependencies."Gtk-4.0"]
+name = "Gtk"
+description = "The GTK toolkit"
+docs_url = "https://docs.gtk.org/gtk4/"
+
+[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 library"
+docs_url = "https://docs.gtk.org/gobject/"
+
+[source-location]
+base_url = "https://gitlab.gnome.org/jpu/casilda/-/blob/@VERSION@/"
+
+[extra]
+urlmap_file = "urlmap.js"

docs/meson.build

@@ -0,0 +1,32 @@
+toml_conf = configuration_data()
+toml_conf.set('VERSION', meson.project_version())
+
+docs_dir = get_option('datadir') / 'doc'
+
+casilda_toml = configure_file(
+  input: 'casilda.toml.in',
+  output: 'casilda.toml',
+  configuration: toml_conf,
+  install: true,
+  install_dir: docs_dir / 'casilda',
+)
+
+custom_target('casilda-doc',
+  input: [ casilda_toml, casilda_gir[0] ],
+  output: 'casilda',
+  command: [
+    gidocgen,
+    'generate',
+    ['--quiet', '--no-namespace-dir'],
+    '--add-include-path=@0@'.format(meson.current_source_dir() / '../src'),
+    '--add-include-path=@0@'.format(meson.current_build_dir() / '../src'),
+    '--config=@INPUT0@',
+    '--output-dir=@OUTPUT@',
+    '--content-dir=@0@'.format(meson.current_source_dir()),
+    '@INPUT1@',
+  ],
+  build_by_default: true,
+  install: true,
+  install_dir: docs_dir,
+  install_tag: 'doc',
+)

docs/urlmap.js

@@ -0,0 +1,10 @@
+// SPDX-FileCopyrightText: 2025 Juan Pablo Ugarte
+// SPDX-License-Identifier: LGPL-2.1-only
+
+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/' ],
+    [ 'Gtk', 'https://docs.gtk.org/gtk4/' ],
+]

meson.build

@@ -42,5 +42,10 @@ config_h.set_quoted('PACKAGE_VERSION', meson.project_version())
 configure_file(output: 'config.h', configuration: config_h)
 add_project_arguments(['-I' + meson.project_build_root()], language: 'c')
 
+gidocgen = find_program('gi-docgen', required: get_option('documentation'), native: true)
+
 subdir('src')
 subdir('examples')
+if get_option('documentation')
+  subdir('docs')
+endif

meson_options.txt

@@ -1,7 +1,12 @@
 option(
     'vapi',
-    
     type: 'boolean',
     value: false,
     description: 'Whether to build vapi files'
 )
+option(
+    'documentation',
+    type: 'boolean',
+    value: false,
+    description : 'Build API reference documentation'
+)