docs: enable building html documentation with hotdoc

.editorconfig

@@ -10,3 +10,7 @@ insert_final_newline = true
 [Makefile]
 indent_style = tab
 indent_size = 8
+
+[docs/sitemap.txt]
+indent_style = tab
+indent_size = 2

README.md

@@ -1,101 +1,13 @@
 # WirePlumber
 
-WirePlumber is a session / policy manager implementation for
+WirePlumber is a modular session / policy manager for
-[PipeWire](https://pipewire.org).
+[PipeWire](https://pipewire.org) and a GObject-based high-level library
+that wraps PipeWire's API, providing convenience for writing the daemon's
+modules as well as external tools for managing PipeWire.
 
-# Compiling and Running
+# Compiling & Running
 
-## Dependencies
+The most recent instructions can be found in the docs:
 
-In order to compile WirePlumber you will need:
+* [Compilation](docs/index.md)
-
+* [Running](docs/daemon.md)
-* GLib >= 2.58
-* PipeWire 0.3 (master)
-
-At the moment, due to heavy development of both PipeWire and WirePlumber,
-it is not always the case that the latest master of WirePlumber works with the
-latest master of PipeWire. The safest PipeWire branch to use with WirePlumber
-master is the `agl-next` branch from
-[my personal clone](https://gitlab.freedesktop.org/gkiagia/pipewire)
-
-## Compilation
-
-WirePlumber uses the meson build system. For compatibility and ease of use,
-though, a Makefile is also provided. The Makefile works only after the initial
-configuration of the project with meson.
-
-Here is the very basic sequence of compiling for the first time:
-```
-$ meson build
-$ make
-```
-
-## Running automated tests
-
-WirePlumber has a few automated tests that you can easily run with:
-
-```
-$ make test
-```
-
-## Running
-
-1. First of all, you will need to run PipeWire. PipeWire itself comes with
-an example session manager that you will need to disable in order to run
-WirePlumber. This can be achieved by editing `src/daemon/pipewire.conf.in`
-on the PipeWire git tree to disable the execution of the session manager:
-
-```
-diff --git a/src/daemon/pipewire.conf.in b/src/daemon/pipewire.conf.in
-index bf64c574..e733e76c 100644
---- a/src/daemon/pipewire.conf.in
-+++ b/src/daemon/pipewire.conf.in
-@@ -24,4 +24,4 @@ load-module libpipewire-module-access
- load-module libpipewire-module-adapter
- load-module libpipewire-module-link-factory
- load-module libpipewire-module-session-manager
--exec build/src/examples/media-session
-+#exec build/src/examples/media-session
-```
-
-2. Second, you will need to run pipewire: in the **pipewire** source tree, do `make run`
-
-3. Without stopping pipewire, in the **wireplumber** source tree, do `make run`
-
-## Testing with an audio client
-
-The easiest way to test that things are working is to start a gstreamer pipeline
-that outputs a test sound to pipewire.
-
-In the **pipewire** source tree, do:
-
-```
-$ make shell
-$ gst-launch-1.0 audiotestsrc ! pwaudiosink
-```
-
-Note that `pwaudiosink` is currently only available in the `agl-next` branch.
-
-## Debugging
-
-The Makefile included with WirePlumber also supports the `gdb` and `valgrind`
-targets. So, instead of `make run` you can do `make gdb` or `make valgrind`
-to do some debugging.
-
-Getting debug messages on the command line is a matter of setting the
-`G_MESSAGES_DEBUG` environment variable as documented in the GLib documentation.
-Usually you can just do:
-
-```
-G_MESSAGES_DEBUG=all make run
-```
-
-Note that this only gives out WirePlumber's debug messages. If you want to also
-see *libpipewire*'s debug messages, then you can also set:
-
-```
-PIPEWIRE_DEBUG=4 G_MESSAGES_DEBUG=all make run
-```
-
-... where `PIPEWIRE_DEBUG` can be set to a value between 1 and 5, with 5 being the
-most verbose and 1 the least verbose.

docs/configuration.md

@@ -1,4 +1,4 @@
-# WirePlumber Configuration
+# Configuration
 
 WirePlumber is a heavily modular daemon. By itself, it doesn't do anything
 except load the configured modules. All the rest of the logic is implemented

docs/daemon.md

@@ -0,0 +1,65 @@
+# Daemon
+
+The WirePlumber daemon implements the session & policy management service.
+
+## Running
+
+1. First of all, you will need to run PipeWire. PipeWire itself comes with
+an example session manager that you will need to disable in order to run
+WirePlumber. This can be achieved by editing `src/daemon/pipewire.conf.in`
+on the PipeWire git tree to disable the execution of the session manager:
+
+```
+diff --git a/src/daemon/pipewire.conf.in b/src/daemon/pipewire.conf.in
+index bf64c574..e733e76c 100644
+--- a/src/daemon/pipewire.conf.in
++++ b/src/daemon/pipewire.conf.in
+@@ -24,4 +24,4 @@ load-module libpipewire-module-access
+ load-module libpipewire-module-adapter
+ load-module libpipewire-module-link-factory
+ load-module libpipewire-module-session-manager
+-exec build/src/examples/media-session
++#exec build/src/examples/media-session
+```
+
+2. Second, you will need to run pipewire: in the **pipewire** source tree, do `make run`
+
+3. Without stopping pipewire, in the **wireplumber** source tree, do `make run`
+
+## Testing with an audio client
+
+The easiest way to test that things are working is to start a gstreamer pipeline
+that outputs a test sound to pipewire.
+
+In the **pipewire** source tree, do:
+
+```
+$ make shell
+$ gst-launch-1.0 audiotestsrc ! pwaudiosink
+```
+
+Note that `pwaudiosink` is currently only available in the `agl-next` branch.
+
+## Debugging
+
+The Makefile included with WirePlumber also supports the `gdb` and `valgrind`
+targets. So, instead of `make run` you can do `make gdb` or `make valgrind`
+to do some debugging.
+
+Getting debug messages on the command line is a matter of setting the
+`G_MESSAGES_DEBUG` environment variable as documented in the GLib documentation.
+Usually you can just do:
+
+```
+G_MESSAGES_DEBUG=all make run
+```
+
+Note that this only gives out WirePlumber's debug messages. If you want to also
+see *libpipewire*'s debug messages, then you can also set:
+
+```
+PIPEWIRE_DEBUG=4 G_MESSAGES_DEBUG=all make run
+```
+
+... where `PIPEWIRE_DEBUG` can be set to a value between 1 and 5, with 5 being the
+most verbose and 1 the least verbose.

docs/index.md

@@ -0,0 +1,41 @@
+# WirePlumber
+
+WirePlumber is a modular session / policy manager for
+[PipeWire](https://pipewire.org) and a GObject-based high-level library
+that wraps PipeWire's API, providing convenience for writing the daemon's
+modules as well as external tools for managing PipeWire.
+
+## Compiling
+
+### Dependencies
+
+In order to compile WirePlumber you will need:
+
+* GLib >= 2.58
+* PipeWire 0.3 (master)
+
+At the moment, due to heavy development of both PipeWire and WirePlumber,
+it is not always the case that the latest master of WirePlumber works with the
+latest master of PipeWire. The safest PipeWire branch to use with WirePlumber
+master is the `agl-next` branch from
+[my personal clone](https://gitlab.freedesktop.org/gkiagia/pipewire)
+
+### Compilation
+
+WirePlumber uses the meson build system. For compatibility and ease of use,
+though, a Makefile is also provided. The Makefile works only after the initial
+configuration of the project with meson.
+
+Here is the very basic sequence of compiling for the first time:
+```
+$ meson build
+$ make
+```
+
+### Running automated tests
+
+WirePlumber has a few automated tests that you can easily run with:
+
+```
+$ make test
+```

docs/library.md

@@ -0,0 +1 @@
+# Library API

docs/meson.build

@@ -0,0 +1,42 @@
+hotdoc_p = find_program('hotdoc', required: get_option('doc'))
+if not hotdoc_p.found()
+  message('Hotdoc not found, not building the documentation')
+  subdir_done()
+endif
+
+hotdoc = import('hotdoc')
+required_hotdoc_extensions = ['gi-extension']
+foreach extension: required_hotdoc_extensions
+  if not hotdoc.has_extensions(extension)
+    if get_option('doc').enabled()
+      error('Documentation enabled but @0@ missing'.format(extension))
+    endif
+
+    message('@0@ extension not found, not building documentation'.format(extension))
+    subdir_done()
+  endif
+endforeach
+
+if not build_gir
+  if get_option('doc').enabled()
+    error('Documentation enabled but introspection not built.')
+  endif
+
+  message('Introspection not built, can\'t build the documentation')
+  subdir_done()
+endif
+
+wp_doc = hotdoc.generate_doc('wireplumber',
+  project_version: wireplumber_api_version,
+  sitemap: 'sitemap.txt',
+  index: 'index.md',
+  gi_index: 'library.md',
+  gi_smart_index: true,
+  gi_sources: [wp_gir[0].full_path()],
+  gi_c_sources: [wp_lib_sources, wp_lib_headers, wpenums_c, wpenums_h],
+  gi_c_source_roots: [join_paths(meson.current_source_dir(), '../lib/wp/'), ],
+  languages: ['c'],
+  dependencies: [wp_dep],
+  build_by_default: true,
+  install: true,
+)

docs/sitemap.txt

@@ -0,0 +1,4 @@
+index.md
+	gi-index
+	daemon.md
+		configuration.md

lib/wp/meson.build

@@ -1,4 +1,4 @@
-wp_lib_sources = [
+wp_lib_sources = files(
   'base-endpoint.c',
   'configuration.c',
   'core.c',
@@ -19,9 +19,9 @@ wp_lib_sources = [
   'proxy-port.c',
   'session.c',
   'spa-props.c',
-]
+)
 
-wp_lib_headers = [
+wp_lib_headers = files(
   'base-endpoint.h',
   'configuration.h',
   'core.h',
@@ -43,7 +43,7 @@ wp_lib_headers = [
   'proxy-link.h',
   'session.h',
   'wp.h',
-]
+)
 
 install_headers(wp_lib_headers,
   subdir : join_paths('wireplumber-' + wireplumber_api_version, 'wp')
@@ -56,9 +56,12 @@ enums = gnome.mkenums_simple('wpenums',
   install_header: true,
   install_dir: join_paths(get_option('includedir'), 'wireplumber-' + wireplumber_api_version, 'wp'),
 )
+wpenums_h = enums[1]
+wpenums_c = enums[0]
+wp_gen_sources = [wpenums_h]
 
 wp_lib = library('wireplumber-' + wireplumber_api_version,
-  wp_lib_sources, enums,
+  wp_lib_sources, wpenums_c, wpenums_h,
   c_args : [
     '-D_GNU_SOURCE',
     '-DG_LOG_USE_STRUCTURED',
@@ -73,21 +76,22 @@ wp_lib = library('wireplumber-' + wireplumber_api_version,
   version: meson.project_version(),
 )
 
-if get_option('introspection')
+if build_gir
-  gnome.generate_gir(wp_lib,
+  wp_gir = gnome.generate_gir(wp_lib,
     namespace: 'Wp',
     nsversion: wireplumber_api_version,
-    sources: [wp_lib_sources, wp_lib_headers, enums],
+    sources: [wp_lib_sources, wp_lib_headers, wpenums_c, wpenums_h],
     includes: ['GLib-2.0', 'GObject-2.0', 'Gio-2.0'],
     install: true,
   )
+  wp_gen_sources += wp_gir
 endif
 
 wp_dep = declare_dependency(
   link_with: wp_lib,
-  sources: enums[1],
+  sources: wp_gen_sources,
   include_directories: wp_lib_include_dir,
-  dependencies: [gobject_dep]
+  dependencies: [gobject_dep, gio_dep]
 )
 
 pkgconfig.generate(wp_lib,

meson.build

@@ -1,7 +1,7 @@
 project('wireplumber', ['c', 'cpp'],
   version : '0.1.90',
   license : 'MIT',
-  meson_version : '>= 0.47.0',
+  meson_version : '>= 0.51.0',
   default_options : [
     'warning_level=1',
     'buildtype=debugoptimized',
@@ -35,6 +35,8 @@ pipewire_dep = dependency('libpipewire-0.3')
 
 gnome = import('gnome')
 pkgconfig = import('pkgconfig')
+gir = find_program('g-ir-scanner', required : get_option('introspection'))
+build_gir = gir.found()
 
 wp_lib_include_dir = include_directories('lib')
 
@@ -49,6 +51,7 @@ if ccpp.has_argument('-fvisibility=hidden')
 endif
 
 subdir('lib')
+subdir('docs')
 subdir('modules')
 subdir('src')
 subdir('tests')

meson_options.txt

@@ -1 +1,4 @@
-option('introspection', type : 'boolean', value : true)
+option('introspection', type : 'feature', value : 'auto',
+       description : 'Generate gobject-introspection bindings')
+option('doc', type : 'feature', value : 'auto',
+       description: 'Enable documentation.')