meson: Add rules for generating the documentation

Both the API reference and the Cookbook.

This requires a little bit of surgery on the Autotools build as well,
namely that we need to stop generating the main gtk-doc XML file from
a template at configuration time; we should, instead, generate and
include a gtkdocentities.ent file both for the Meson build (where we
generate the file ourselves) and for the Autotools build (where
gtk-doc.make does it for us).

6 files changed, 341 insertions, 5 deletions

diff --git a/doc/cookbook/meson.build b/doc/cookbook/meson.build
new file mode 100644
index 000000000..8c2ea66b5
--- /dev/null
+++ b/doc/cookbook/meson.build
@@ -0,0 +1,65 @@
+xml_files = [
+  'actors.xml',
+  'animations.xml',
+  'events.xml',
+  'introduction.xml',
+  'text.xml',
+  'textures.xml',
+  'layouts.xml',
+  'script.xml',
+  'effects.xml',
+]
+
+xsltproc_options = [
+  '--stringparam', 'html.stylesheet', 'style.css',
+  '--stringparam', 'chapter.autolabel', '1',
+  '--stringparam', 'appending.autolabel', '1',
+  '--stringparam', 'section.autolabel', '1',
+  '--stringparam', 'gtkdoc.bookname', 'clutter-cookbook',
+  '--stringparam', 'gtkdoc.version', clutter_api_version,
+  '--stringparam', 'callout.graphics', '0',
+  '--path', join_paths(meson.current_source_dir()),
+  '--xinclude',
+]
+
+xsltproc = find_program('xsltproc', required: false)
+
+docbook_xsl = 'http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl'
+
+cookbook_xml_conf = configuration_data()
+cookbook_xml_conf.set('CLUTTER_API_VERSION', clutter_api_version)
+
+cookbook_dir = join_paths(clutter_datadir, 'gtk-doc', 'html')
+
+if xsltproc.found()
+  cmd = run_command([xsltproc, '--nonet', docbook_xsl])
+  have_docbook_xsl = cmd.returncode() == 0
+
+  if have_docbook_xsl
+    custom_target('clutter-cookbook',
+      command: [
+        xsltproc,
+        xsltproc_options,
+        '-o', '@OUTPUT@/',
+        'cookbook.xsl',
+        '@INPUT@',
+      ],
+      input: configure_file(
+        input: 'clutter-cookbook.xml.in',
+        output: 'clutter-cookbook.xml',
+        configuration: cookbook_xml_conf,
+      ),
+      output: 'clutter-cookbook',
+      install: true,
+      install_dir: cookbook_dir,
+    )
+
+    install_data('style.css', install_dir: join_paths(cookbook_dir, 'clutter-cookbook'))
+    install_subdir('images', install_dir: join_paths(cookbook_dir, 'clutter-cookbook'))
+    install_subdir('videos', install_dir: join_paths(cookbook_dir, 'clutter-cookbook'))
+  else
+    message('Cookbook not available, requires Docbook XSL')
+  endif
+else
+  message('Cookbook not available, requires xsltproc')
+endif
diff --git a/doc/meson.build b/doc/meson.build
index e69de29bb..b4fa88777 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -0,0 +1,2 @@
+subdir('reference')
+subdir('cookbook')
diff --git a/doc/reference/clutter-docs.xml.in b/doc/reference/clutter-docs.xml
index baa0e4c21..8f7b936a5 100644
--- a/doc/reference/clutter-docs.xml.in
+++ b/doc/reference/clutter-docs.xml
@@ -1,13 +1,15 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-               "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY version "@VERSION@">
+<!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="clutter" lang="en" xmlns:xi="http://www.w3.org/2003/XInclude">
+<book id="clutter" lang="en">
   <bookinfo>
     <title>Clutter Reference Manual</title>
-    <releaseinfo>for Clutter &version;</releaseinfo>
+    <releaseinfo>for Clutter &PACKAGE_VERSION;</releaseinfo>
 
     <copyright>
       <year>2006</year>
diff --git a/doc/reference/meson.build b/doc/reference/meson.build
index e69de29bb..c94a161bf 100644
--- a/doc/reference/meson.build
+++ b/doc/reference/meson.build
@@ -0,0 +1,244 @@
+private_headers = [
+  'config.h',
+  'clutter.h',
+
+  'clutter-actor-meta-private.h',
+  'clutter-actor-private.h',
+  'clutter-backend-private.h',
+  'clutter-bezier.h',
+  'clutter-cogl-compat.h',
+  'clutter-color-static.h',
+  'clutter-config.h',
+  'clutter-constraint-private.h',
+  'clutter-debug.h',
+  'clutter-deprecated.h ',
+  'clutter-device-manager-private.h',
+  'clutter-easing.h',
+  'clutter-enum-types.h ',
+  'clutter-event-translator.h',
+  'clutter-flatten-effect.h',
+  'clutter-gesture-action-private.h',
+  'clutter-id-pool.h',
+  'clutter-keysyms.h',
+  'clutter-keysyms-compat.h',
+  'clutter-keysyms-table.h',
+  'clutter-marshal.h',
+  'clutter-master-clock-default.h',
+  'clutter-master-clock.h',
+  'clutter-model-private.h',
+  'clutter-paint-node-private.h',
+  'clutter-paint-volume-private.h',
+  'clutter-private.h',
+  'clutter-script-private.h',
+  'clutter-settings-private.h',
+  'clutter-stage-manager-private.h',
+  'clutter-stage-private.h',
+  'clutter-stage-window.h',
+  'clutter-timeout-interval.h',
+
+  # Cally
+  'cally-actor-private.h',
+
+  # No public symbols
+  'tslib',
+  'cogl',
+]
+
+doc_dirs = [
+  clutter_inc,
+]
+
+# Backend headers
+if enabled_backends.contains('cex100')
+  private_headers += [
+    'clutter-backend-cex100.h',
+  ]
+else
+  private_headers += 'cex100'
+endif
+
+if enabled_backends.contains('eglnative')
+  private_headers += [
+    'clutter-backend-eglnative.h',
+    'clutter-egl-headers.h',
+    'clutter-stage-eglnative.h',
+  ]
+else
+  private_headers += 'egl'
+endif
+
+if enabled_input_backends.contains('evdev')
+  private_headers += [
+    'clutter-device-manager-evdev.h',
+    'clutter-input-device-evdev.h',
+    'clutter-xkb-utils.h',
+  ]
+else
+  private_headers += 'evdev'
+endif
+
+if enabled_backends.contains('gdk')
+  private_headers += [
+    'clutter-backend-gdk.h',
+    'clutter-backend-gk-private.h',
+    'clutter-device-manager-gdk.h',
+    'clutter-event-gdk.h',
+    'clutter-input-device-gdk.h',
+    'clutter-master-clock-gdk.h',
+    'clutter-settings-gdk.h',
+    'clutter-stage-gdk.h',
+  ]
+else
+  private_headers += 'gdk'
+endif
+
+if enabled_backends.contains('mir')
+  private_headers += [
+    'clutter-backend-mir.h',
+    'clutter-backend-mir-priv.h',
+    'clutter-device-manager-mir.h',
+    'clutter-event-mir.h',
+    'clutter-input-device-mir.h',
+    'clutter-stage-mir.h',
+  ]
+else
+  private_headers += 'mir'
+endif
+
+if enabled_backends.contains('osx')
+  private_headers += [
+    'clutter-backend-osx.h',
+    'clutter-device-manager-osx.h',
+    'clutter-event-loop-osx.h',
+    'clutter-stage-osx.h',
+  ]
+else
+  private_headers += 'osx'
+endif
+
+if enabled_backends.contains('wayland')
+  private_headers += [
+    'clutter-backend-wayland.h',
+    'clutter-backend-wayland-priv.h',
+    'clutter-device-manager-wayland.h',
+    'clutter-event-wayland.h',
+    'clutter-input-device-wayland.h',
+    'clutter-stage-wayland.h',
+  ]
+else
+  private_headers += 'wayland'
+endif
+
+if enabled_backends.contains('win32')
+  private_headers += [
+    'clutter-backend-win32.h',
+    'clutter-device-manager-win32.h',
+    'clutter-event-win32.h',
+    'clutter-stage-win32.h',
+  ]
+else
+  private_headers += 'win32'
+endif
+
+if enabled_backends.contains('x11')
+  private_headers += [
+    'clutter-backend-x11.h',
+    'clutter-device-manager-core-x11.h',
+    'clutter-device-manager-xi2.h',
+    'clutter-input-device-core-x11.h',
+    'clutter-input-device-xi2.h',
+    'clutter-keymap-x11.h',
+    'clutter-settings-x11.h',
+    'clutter-stage-x11.h',
+    'xsettings',
+  ]
+else
+  private_headers += [ 'x11', 'xsettings' ]
+endif
+
+images = [
+  'actor-box.png',
+  'actor-example.png',
+  'animator-key-frames.png',
+  'bin-layout.png',
+  'box-layout.png',
+  'constraints-example.png',
+  'easing-modes.png',
+  'event-flow.png',
+  'flow-layout.png',
+  'path-alpha-func.png',
+  'offscreen-redirect.png',
+  'table-layout.png',
+]
+
+content_files = [
+  'glossary.xml',
+  'clutter-overview.xml',
+  'building-clutter.xml',
+  'running-clutter.xml',
+  'migrating-ClutterAnimation.xml',
+  'migrating-ClutterBehaviour.xml',
+  'migrating-ClutterEffect.xml',
+  'migrating-ClutterPath.xml',
+]
+
+expand_content_files = [
+  'glossary.xml',
+  'clutter-overview.xml',
+  'building-clutter.xml',
+  'running-clutter.xml',
+  'migrating-ClutterAnimation.xml',
+  'migrating-ClutterBehaviour.xml',
+  'migrating-ClutterEffect.xml',
+  'migrating-ClutterPath.xml',
+]
+
+docpath = join_paths(get_option('prefix'), get_option('datadir'), 'gtk-doc', 'html')
+
+glib_prefix = dependency('glib-2.0').get_pkgconfig_variable('prefix')
+glib_docpath = join_paths(glib_prefix, 'share', 'gtk-doc', 'html')
+
+cairo_prefix = dependency('cairo').get_pkgconfig_variable('prefix')
+cairo_docpath = join_paths(cairo_prefix, 'share', 'gtk-doc', 'html', 'cairo')
+
+cogl_prefix = dependency('cogl-1.0').get_pkgconfig_variable('prefix')
+cogl_docpath = join_paths(cogl_prefix, 'share', 'gtk-doc', 'html', 'cogl')
+
+pango_prefix = dependency('pango').get_pkgconfig_variable('prefix')
+pango_docpath = join_paths(cogl_prefix, 'share', 'gtk-doc', 'html', 'pango')
+
+gdk_prefix = dependency('gdk-3.0').get_pkgconfig_variable('prefix')
+gdk_docpath = join_paths(cogl_prefix, 'share', 'gtk-doc', 'html', 'gdk3')
+
+atk_prefix = dependency('atk').get_pkgconfig_variable('prefix')
+atk_docpath = join_paths(cogl_prefix, 'share', 'gtk-doc', 'html', 'atk')
+
+subdir('xml')
+
+gnome.gtkdoc('clutter',
+  main_xml: 'clutter-docs.xml',
+  mode: 'xml',
+  namespace: 'clutter',
+  src_dir: doc_dirs,
+  dependencies: libclutter_dep,
+  gobject_typesfile: join_paths(meson.current_source_dir(), 'clutter.types'),
+  scan_args: [
+    '--ignore-decorators=_CLUTTER_EXTERN',
+    '--ignore-headers=' + ' '.join(private_headers),
+  ],
+  fixxref_args: [
+    '--html-dir=@0@'.format(docpath),
+    '--extra-dir=@0@'.format(join_paths(glib_docpath, 'glib')),
+    '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gobject')),
+    '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gio')),
+    '--extra-dir=@0@'.format(cairo_docpath),
+    '--extra-dir=@0@'.format(cogl_docpath),
+    '--extra-dir=@0@'.format(pango_docpath),
+    '--extra-dir=@0@'.format(gdk_docpath),
+    '--extra-dir=@0@'.format(atk_docpath),
+  ],
+  content_files: content_files,
+  expand_content_files: expand_content_files,
+  html_assets: images,
+  install: true,
+)
diff --git a/doc/reference/xml/gtkdocentities.ent.in b/doc/reference/xml/gtkdocentities.ent.in
new file mode 100644
index 000000000..f12c9ff74
--- /dev/null
+++ b/doc/reference/xml/gtkdocentities.ent.in
@@ -0,0 +1,8 @@
+<!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@">
+<!ENTITY package_api_version "@PACKAGE_API_VERSION@">
diff --git a/doc/reference/xml/meson.build b/doc/reference/xml/meson.build
new file mode 100644
index 000000000..3bc808157
--- /dev/null
+++ b/doc/reference/xml/meson.build
@@ -0,0 +1,15 @@
+# Create XML entities like the ones gtk-doc.make provides
+ent_conf = configuration_data()
+ent_conf.set('PACKAGE', 'Clutter')
+ent_conf.set('PACKAGE_BUGREPORT', 'https://gitlab.gnome.org/GNOME/@0@/issues'.format(meson.project_name()))
+ent_conf.set('PACKAGE_NAME', meson.project_name())
+ent_conf.set('PACKAGE_STRING', meson.project_name())
+ent_conf.set('PACKAGE_TARNAME', '@0@-@1@'.format(meson.project_name(), meson.project_version()))
+ent_conf.set('PACKAGE_URL', '')
+ent_conf.set('PACKAGE_VERSION', meson.project_version())
+ent_conf.set('PACKAGE_API_VERSION', clutter_api_version)
+configure_file(
+  input: 'gtkdocentities.ent.in',
+  output: 'gtkdocentities.ent',
+  configuration: ent_conf,
+)