docs: Re-enable generating the reference manual

gtk-doc support was removed around 3 years ago with commit 7dc0b0e6.
Now that we have Meson and [MRs related to documentation], it makes
sense to re-enable this, so people who want to use libmutter can do so
without having to actually dive in the code.

[MRs related to documentation]: https://gitlab.gnome.org/GNOME/mutter/merge_requests/269

doc/meson.build

@@ -0,0 +1,100 @@
+# manpage
+subdir('man')
+
+# Reference manual
+subdir('xml')
+
+version_conf = configuration_data()
+version_conf.set('VERSION', meson.project_version())
+version_xml = configure_file(
+  input: 'version.xml.in',
+  output: 'version.xml',
+  configuration: version_conf
+)
+
+reference_ignored_headers = [
+  'config.h',
+
+  'bell.h',
+  'boxes-private.h',
+  'compositor-private.h',
+  'core.h',
+  'constraints.h',
+  'display-private.h',
+  'frame.h',
+  'frames.h',
+  'group-private.h',
+  'keybindings-private.h',
+  'main.h',
+  'meta-backend-private.h',
+  'meta-background-private.h',
+  'meta-barrier-private.h',
+  'meta-dnd-actor-private.h',
+  'meta-dnd-private.h',
+  'meta-feedback-actor-private.h',
+  'meta-gesture-tracker-private.h',
+  'meta-idle-monitor-private.h',
+  'meta-input-mapper-private.h',
+  'meta-input-settings-private.h',
+  'meta-monitor-manager-private.h',
+  'meta-remote-access-controller-private.h',
+  'meta-settings-private.h',
+  'meta-shaped-texture-private.h',
+  'meta-stage-private.h',
+  'meta-wayland-private.h',
+  'meta-window-actor-private.h',
+  'meta-window-group-private.h',
+  'meta-xwayland-private.h',
+  'meta-xwayland-selection-private.h',
+  'theme-private.h',
+  'util-private.h',
+  'window-private.h',
+  'window-x11-private.h',
+  'workspace-private.h',
+  # Test headers
+  'meta-backend-test.h',
+  'meta-monitor-manager-test.h',
+  'meta-wayland-egl-stream.h',
+  'meta-wayland-inhibit-shortcuts.h',
+  'meta-wayland-text-input.h',
+  'meta-xwayland-grab-keyboard.h',
+]
+
+# Make sure we ignore the wayland headers
+if have_wayland
+  foreach proto : wayland_protocols
+    protocol_name = proto[0]
+    protocol_type = proto[1]
+    if protocol_type == 'stable'
+      output_base = protocol_name
+    elif protocol_type == 'private'
+      output_base = protocol_name
+    elif protocol_type == 'third-party'
+      output_base = protocol_name
+    else
+      protocol_version = proto[2]
+      output_base = '@0@-@1@-@2@'.format(protocol_name,
+                                         protocol_type,
+                                         protocol_version)
+    endif
+
+    proto_header = '@0@-server-protocol.h'.format(output_base)
+    reference_ignored_headers += proto_header
+  endforeach
+endif
+
+
+gnome.gtkdoc(meson.project_name(),
+  main_sgml: 'mutter-docs.sgml',
+  src_dir: [
+    include_directories('../src'),
+  ],
+  dependencies: _libmutter_public_symbols_dep,
+  gobject_typesfile: 'mutter.types',
+  scan_args: [
+    '--rebuild-types',
+    '--ignore-headers=' + ' '.join(reference_ignored_headers),
+    '--ignore-decorators=META_EXPORT|META_EXPORT_TEST',
+  ],
+  install: true,
+)

doc/mutter-docs.sgml

@@ -0,0 +1,110 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+  <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
+  %gtkdocentities;
+]>
+<book id="index">
+  <bookinfo>
+    <title>Mutter Reference Manual</title>
+    <releaseinfo>
+      For &package_string;.
+      The latest version of this documentation can be found on-line at
+      <ulink role="online-location" url="http://[SERVER]/&package_name;/index.html">http://[SERVER]/&package_name;/</ulink>.
+    </releaseinfo>
+  </bookinfo>
+
+  <chapter>
+    <title>General</title>
+    <xi:include href="xml/meta-backend.xml"/>
+    <xi:include href="xml/meta-clutter-backend-native.xml"/>
+    <xi:include href="xml/meta-renderer.xml"/>
+    <xi:include href="xml/meta-stage.xml"/>
+  </chapter>
+
+  <chapter>
+    <title>Clutter actors</title>
+    <xi:include href="xml/meta-window-actor.xml"/>
+    <xi:include href="xml/meta-window-group.xml"/>
+    <xi:include href="xml/meta-background-actor.xml"/>
+    <xi:include href="xml/meta-background-group.xml"/>
+    <xi:include href="xml/meta-surface-actor.xml"/>
+    <xi:include href="xml/meta-shaped-texture.xml"/>
+  </chapter>
+
+  <chapter>
+    <title>Plugins</title>
+    <xi:include href="xml/meta-plugin.xml"/>
+    <xi:include href="xml/meta-plugin-manager.xml"/>
+  </chapter>
+
+  <chapter>
+    <title>Cursor management</title>
+    <xi:include href="xml/meta-cursor-tracker.xml"/>
+    <xi:include href="xml/meta-cursor.xml"/>
+    <xi:include href="xml/meta-cursor-renderer.xml"/>
+    <xi:include href="xml/meta-pointer-constraint.xml"/>
+  </chapter>
+
+  <chapter>
+    <title>Monitor management</title>
+    <xi:include href="xml/meta-monitor-manager.xml"/>
+    <xi:include href="xml/meta-monitor-manager-dummy.xml"/>
+    <xi:include href="xml/meta-monitor-config-manager.xml"/>
+    <xi:include href="xml/meta-logical-monitor.xml"/>
+    <xi:include href="xml/meta-monitor.xml"/>
+    <xi:include href="xml/meta-monitor-transform.xml"/>
+  </chapter>
+
+  <chapter>
+    <title>X11</title>
+    <xi:include href="xml/meta-backend-x11.xml"/>
+    <xi:include href="xml/meta-monitor-manager-xrandr.xml"/>
+    <xi:include href="xml/meta-window-actor-x11.xml"/>
+    <xi:include href="xml/meta-surface-actor-x11.xml"/>
+  </chapter>
+
+  <chapter>
+    <title>Native / Wayland</title>
+    <xi:include href="xml/meta-backend-native.xml"/>
+    <xi:include href="xml/meta-monitor-manager-kms.xml"/>
+    <xi:include href="xml/meta-renderer-native.xml"/>
+    <xi:include href="xml/meta-window-actor-wayland.xml"/>
+    <xi:include href="xml/meta-surface-actor-wayland.xml"/>
+  </chapter>
+
+  <chapter>
+    <title>Screencast</title>
+    <xi:include href="xml/meta-screen-cast.xml"/>
+    <xi:include href="xml/meta-screen-cast-session.xml"/>
+    <xi:include href="xml/meta-screen-cast-window.xml"/>
+    <xi:include href="xml/meta-screen-cast-stream.xml"/>
+    <xi:include href="xml/meta-screen-cast-window-stream.xml"/>
+    <xi:include href="xml/meta-screen-cast-monitor-stream.xml"/>
+    <xi:include href="xml/meta-screen-cast-stream-src.xml"/>
+    <xi:include href="xml/meta-screen-cast-window-stream-src.xml"/>
+    <xi:include href="xml/meta-screen-cast-monitor-stream-src.xml"/>
+  </chapter>
+
+  <chapter>
+    <title>Remote desktop</title>
+    <xi:include href="xml/meta-remote-desktop.xml"/>
+    <xi:include href="xml/meta-dbus-remote-desktop.xml"/>
+  </chapter>
+
+  <chapter id="object-tree">
+    <title>Object Hierarchy</title>
+    <xi:include href="xml/tree_index.sgml"/>
+  </chapter>
+  <index id="api-index-full">
+    <title>API Index</title>
+    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="deprecated-api-index" role="deprecated">
+    <title>Index of deprecated API</title>
+    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+  </index>
+  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+</book>

doc/version.xml.in

@@ -0,0 +1 @@
+@VERSION@

doc/xml/gtkdocentities.ent.in

@@ -0,0 +1,7 @@
+<!ENTITY package @PACKAGE@>
+<!ENTITY package_bugreport @PACKAGE_BUGREPORT@>
+<!ENTITY package_name @PACKAGE_NAME@>
+<!ENTITY package_string @PACKAGE_STRING@>
+<!ENTITY package_tarname @PACKAGE_TARNAME@>
+<!ENTITY package_url @PACKAGE_URL@>
+<!ENTITY package_version @PACKAGE_VERSION@>

doc/xml/meson.build

@@ -0,0 +1,13 @@
+gtkdoc_entities_cdata = configuration_data()
+gtkdoc_entities_cdata.set_quoted('PACKAGE', meson.project_name())
+gtkdoc_entities_cdata.set_quoted('PACKAGE_BUGREPORT', 'https://gitlab.gnome.org/GNOME/mutter/issues/new')
+gtkdoc_entities_cdata.set_quoted('PACKAGE_NAME', meson.project_name())
+gtkdoc_entities_cdata.set_quoted('PACKAGE_STRING', '@0@ - @1@'.format(meson.project_name(), meson.project_version()))
+gtkdoc_entities_cdata.set_quoted('PACKAGE_TARNAME', 'mutter.tar.xz')
+gtkdoc_entities_cdata.set_quoted('PACKAGE_URL', 'https://gitlab.gnome.org/GNOME/mutter/')
+gtkdoc_entities_cdata.set_quoted('PACKAGE_VERSION', meson.project_version())
+configure_file(
+  input: 'gtkdocentities.ent.in',
+  output: 'gtkdocentities.ent',
+  configuration: gtkdoc_entities_cdata,
+)

meson.build

@@ -370,7 +370,7 @@ subdir('clutter')
 subdir('data')
 subdir('src')
 subdir('po')
-subdir('doc/man')
+subdir('doc')
 
 output = [
   '',

src/backends/meta-cursor-tracker.c

@@ -20,7 +20,7 @@
  */
 
 /**
- * SECTION:cursor-tracker
+ * SECTION:meta-cursor-tracker
  * @title: MetaCursorTracker
  * @short_description: Mutter cursor tracking helper. Originally only
  *                     tracking the cursor image, now more of a "core

src/meson.build

@@ -778,6 +778,32 @@ libmutter_dep = declare_dependency(
   ],
 )
 
+# Interal library for gtk-doc (we need symbol visibility)
+_libmutter_public_symbols = library(libmutter_name + '-public-symbols',
+  sources: [
+    mutter_sources,
+    mutter_built_sources,
+  ],
+  include_directories: mutter_includes,
+  c_args: mutter_c_args,
+  dependencies: [
+    libmutter_cogl_dep,
+    libmutter_clutter_dep,
+    mutter_deps,
+  ],
+)
+
+_libmutter_public_symbols_dep = declare_dependency(
+  link_with: _libmutter_public_symbols,
+  include_directories: mutter_includes,
+  sources: mutter_built_sources,
+  dependencies: [
+    libmutter_cogl_dep,
+    libmutter_clutter_dep,
+    mutter_deps,
+  ],
+)
+
 executable('mutter',
   sources: [
     files('core/mutter.c'),