From 7662c0e332c3183bc40b93a778b1045a4a4a22b6 Mon Sep 17 00:00:00 2001 From: Juan Pablo Ugarte Date: Thu, 28 Aug 2025 08:42:01 -0400 Subject: [PATCH] Add API reference generation using gi-docgen --- CHANGELOG.md | 44 ++++++++++----------------------------- README.md | 49 ++++++++------------------------------------ docs/casilda.toml.in | 40 ++++++++++++++++++++++++++++++++++++ docs/meson.build | 32 +++++++++++++++++++++++++++++ docs/urlmap.js | 10 +++++++++ meson.build | 5 +++++ meson_options.txt | 7 ++++++- 7 files changed, 113 insertions(+), 74 deletions(-) create mode 100644 docs/casilda.toml.in create mode 100644 docs/meson.build create mode 100644 docs/urlmap.js diff --git a/CHANGELOG.md b/CHANGELOG.md index 87e5b4f..cb82c91 100644 --- a/CHANGELOG.md +++ b/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 - - 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) + - 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 ### 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) diff --git a/README.md b/README.md index 9d2b159..07c56a4 100644 --- a/README.md +++ b/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 -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. - -``` +```c 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. - -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. +Casilda uses gi-docgen to generate it API reference documentation ## Contributing diff --git a/docs/casilda.toml.in b/docs/casilda.toml.in new file mode 100644 index 0000000..fe45442 --- /dev/null +++ b/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" \ No newline at end of file diff --git a/docs/meson.build b/docs/meson.build new file mode 100644 index 0000000..3729996 --- /dev/null +++ b/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', +) \ No newline at end of file diff --git a/docs/urlmap.js b/docs/urlmap.js new file mode 100644 index 0000000..badc30c --- /dev/null +++ b/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/' ], +] diff --git a/meson.build b/meson.build index 23a8816..c95c15b 100644 --- a/meson.build +++ b/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 diff --git a/meson_options.txt b/meson_options.txt index 5d94e20..e27a9d2 100644 --- a/meson_options.txt +++ b/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' +) \ No newline at end of file