gtkdoc: Add 'check' kwarg (#5591)

* gtkdoc: Add 'check' kwarg

This runs gtkdoc-check in meson tests.

Also reorganize the gtkdoc test because we cannot reliably build
multiple doc into the same directory. Not all files generated by gtk-doc
are prefixed with the target name.

12 files changed, 228 insertions, 29 deletions

diff --git a/docs/markdown/Gnome-module.md b/docs/markdown/Gnome-module.md
index dcd843f..9d8029e 100644
--- a/docs/markdown/Gnome-module.md
+++ b/docs/markdown/Gnome-module.md
@@ -339,10 +339,16 @@ of the module.
 * `scanobjs_args`: a list of arguments to pass to `gtkdoc-scangobj`
 * `c_args`: (*Added 0.48.0*) additional compile arguments to pass
 * `src_dir`: include_directories to include
+* `check`: (*Since 0.52.0*) if `true` runs `gtkdoc-check` when running unit tests.
+  Note that this has the downside of rebuilding the doc for each build, which is
+  often very slow. It usually should be enabled only in CI.
 
 This creates a `$module-doc` target that can be ran to build docs and
 normally these are only built on install.
 
+*Since 0.52.0* Returns a target object that can be passed as dependency to other
+targets using generated doc files (e.g. in `content_files` of another doc).
+
 ### gnome.gtkdoc_html_dir()
 
 Takes as argument a module name and returns the path where that
diff --git a/docs/markdown/snippets/gtkdoc.md b/docs/markdown/snippets/gtkdoc.md
new file mode 100644
index 0000000..f1f4ed4
--- /dev/null
+++ b/docs/markdown/snippets/gtkdoc.md
@@ -0,0 +1,11 @@
+## gtkdoc-check support
+
+`gnome.gtkdoc()` now has a `check` keyword argument. If `true` runs it will run
+`gtkdoc-check` when running unit tests. Note that this has the downside of
+rebuilding the doc for each build, which is often very slow. It usually should
+be enabled only in CI.
+
+## `gnome.gtkdoc()` returns target object
+
+`gnome.gtkdoc()` now returns a target object that can be passed as dependency to
+other targets using generated doc files (e.g. in `content_files` of another doc).
diff --git a/mesonbuild/modules/gnome.py b/mesonbuild/modules/gnome.py
index aa815c7..f67c7c2 100644
--- a/mesonbuild/modules/gnome.py
+++ b/mesonbuild/modules/gnome.py
@@ -913,6 +913,7 @@ This will become a hard error in the future.''')
         rv = [inscript, pottarget, potarget]
         return ModuleReturnValue(None, rv)
 
+    @FeatureNewKwargs('gnome.gtkdoc', '0.52.0', ['check'])
     @FeatureNewKwargs('gnome.gtkdoc', '0.48.0', ['c_args'])
     @FeatureNewKwargs('gnome.gtkdoc', '0.48.0', ['module_version'])
     @FeatureNewKwargs('gnome.gtkdoc', '0.37.0', ['namespace', 'mode'])
@@ -1019,10 +1020,26 @@ This will become a hard error in the future.''')
         args += self._unpack_args('--ignore-headers=', 'ignore_headers', kwargs)
         args += self._unpack_args('--installdir=', 'install_dir', kwargs)
         args += self._get_build_args(kwargs, state, depends)
-        res = [build.RunTarget(targetname, command[0], command[1:] + args, depends, state.subdir, state.subproject)]
+        custom_kwargs = {'output': modulename + '-decl.txt',
+                         'command': command + args,
+                         'depends': depends,
+                         'build_always_stale': True,
+                         }
+        custom_target = build.CustomTarget(targetname, state.subdir, state.subproject, custom_kwargs)
+        alias_target = build.AliasTarget(targetname, [custom_target], state.subdir, state.subproject)
+        if kwargs.get('check', False):
+            check_cmd = self.interpreter.find_program_impl('gtkdoc-check')
+            check_env = ['DOC_MODULE=' + modulename,
+                         'DOC_MAIN_SGML_FILE=' + main_file]
+            check_args = [targetname + '-check', check_cmd]
+            check_kwargs = {'env': check_env,
+                            'workdir': os.path.join(state.environment.get_build_dir(), state.subdir),
+                            'depends': custom_target}
+            self.interpreter.add_test(state.current_node, check_args, check_kwargs, True)
+        res = [custom_target, alias_target]
         if kwargs.get('install', True):
             res.append(build.RunScript(command, args))
-        return ModuleReturnValue(None, res)
+        return ModuleReturnValue(custom_target, res)
 
     def _get_build_args(self, kwargs, state, depends):
         args = []
diff --git a/test cases/frameworks/10 gtk-doc/doc/foobar1/foobar-docs.sgml b/test cases/frameworks/10 gtk-doc/doc/foobar1/foobar-docs.sgml
new file mode 100644
index 0000000..95f73ef
--- /dev/null
+++ b/test cases/frameworks/10 gtk-doc/doc/foobar1/foobar-docs.sgml
@@ -0,0 +1,41 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "../version.xml">
+]>
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <bookinfo>
+    <title>Foolib Reference Manual</title>
+    <releaseinfo>
+      for Foobar &version;
+    </releaseinfo>
+    <authorgroup>
+      <author>
+        <firstname>Jonny</firstname>
+        <surname>Example</surname>
+        <affiliation>
+          <address>
+            <email>unknown@example.com</email>
+          </address>
+        </affiliation>
+      </author>
+    </authorgroup>
+    <copyright>
+      <year>2015</year>
+      <holder>Foobar corporation holdings ltd</holder>
+    </copyright>
+  </bookinfo>
+
+  <reference id="foobar">
+    <title>Foobar library</title>
+    <partintro>
+      <para>
+        This part documents Foobar libs.
+      </para>
+    </partintro>
+    <xi:include href="xml/foo.xml"/>
+    <xi:include href="../../include/bar.xml"/>
+    <xi:include href="xml/foo-version.xml"/>
+  </reference>
+
+</book>
diff --git a/test cases/frameworks/10 gtk-doc/doc/foobar1/meson.build b/test cases/frameworks/10 gtk-doc/doc/foobar1/meson.build
new file mode 100644
index 0000000..149c6e9
--- /dev/null
+++ b/test cases/frameworks/10 gtk-doc/doc/foobar1/meson.build
@@ -0,0 +1,5 @@
+gnome.gtkdoc('foobar',
+  src_dir : inc,
+  main_sgml : 'foobar-docs.sgml',
+  content_files : [docbook, version_xml],
+  install : true)
diff --git a/test cases/frameworks/10 gtk-doc/doc/foobar2/foobar-docs.sgml b/test cases/frameworks/10 gtk-doc/doc/foobar2/foobar-docs.sgml
new file mode 100644
index 0000000..95f73ef
--- /dev/null
+++ b/test cases/frameworks/10 gtk-doc/doc/foobar2/foobar-docs.sgml
@@ -0,0 +1,41 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "../version.xml">
+]>
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <bookinfo>
+    <title>Foolib Reference Manual</title>
+    <releaseinfo>
+      for Foobar &version;
+    </releaseinfo>
+    <authorgroup>
+      <author>
+        <firstname>Jonny</firstname>
+        <surname>Example</surname>
+        <affiliation>
+          <address>
+            <email>unknown@example.com</email>
+          </address>
+        </affiliation>
+      </author>
+    </authorgroup>
+    <copyright>
+      <year>2015</year>
+      <holder>Foobar corporation holdings ltd</holder>
+    </copyright>
+  </bookinfo>
+
+  <reference id="foobar">
+    <title>Foobar library</title>
+    <partintro>
+      <para>
+        This part documents Foobar libs.
+      </para>
+    </partintro>
+    <xi:include href="xml/foo.xml"/>
+    <xi:include href="../../include/bar.xml"/>
+    <xi:include href="xml/foo-version.xml"/>
+  </reference>
+
+</book>
diff --git a/test cases/frameworks/10 gtk-doc/doc/foobar2/meson.build b/test cases/frameworks/10 gtk-doc/doc/foobar2/meson.build
new file mode 100644
index 0000000..0b2faa0
--- /dev/null
+++ b/test cases/frameworks/10 gtk-doc/doc/foobar2/meson.build
@@ -0,0 +1,6 @@
+gnome.gtkdoc('foobar2',
+  src_dir : inc,
+  main_sgml : 'foobar-docs.sgml',
+  content_files : [docbook, version_xml],
+  install : true,
+  install_dir : 'foobar2')
diff --git a/test cases/frameworks/10 gtk-doc/doc/foobar3/foobar-docs.sgml b/test cases/frameworks/10 gtk-doc/doc/foobar3/foobar-docs.sgml
new file mode 100644
index 0000000..95f73ef
--- /dev/null
+++ b/test cases/frameworks/10 gtk-doc/doc/foobar3/foobar-docs.sgml
@@ -0,0 +1,41 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "../version.xml">
+]>
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <bookinfo>
+    <title>Foolib Reference Manual</title>
+    <releaseinfo>
+      for Foobar &version;
+    </releaseinfo>
+    <authorgroup>
+      <author>
+        <firstname>Jonny</firstname>
+        <surname>Example</surname>
+        <affiliation>
+          <address>
+            <email>unknown@example.com</email>
+          </address>
+        </affiliation>
+      </author>
+    </authorgroup>
+    <copyright>
+      <year>2015</year>
+      <holder>Foobar corporation holdings ltd</holder>
+    </copyright>
+  </bookinfo>
+
+  <reference id="foobar">
+    <title>Foobar library</title>
+    <partintro>
+      <para>
+        This part documents Foobar libs.
+      </para>
+    </partintro>
+    <xi:include href="xml/foo.xml"/>
+    <xi:include href="../../include/bar.xml"/>
+    <xi:include href="xml/foo-version.xml"/>
+  </reference>
+
+</book>
diff --git a/test cases/frameworks/10 gtk-doc/doc/foobar3/meson.build b/test cases/frameworks/10 gtk-doc/doc/foobar3/meson.build
new file mode 100644
index 0000000..0dce2f8
--- /dev/null
+++ b/test cases/frameworks/10 gtk-doc/doc/foobar3/meson.build
@@ -0,0 +1,6 @@
+gnome.gtkdoc('foobar',
+  module_version : '3.0',
+  src_dir : inc,
+  main_sgml : 'foobar-docs.sgml',
+  content_files : [docbook, version_xml],
+  install : true)
diff --git a/test cases/frameworks/10 gtk-doc/doc/foobar4/foobar-docs.sgml b/test cases/frameworks/10 gtk-doc/doc/foobar4/foobar-docs.sgml
new file mode 100644
index 0000000..95f73ef
--- /dev/null
+++ b/test cases/frameworks/10 gtk-doc/doc/foobar4/foobar-docs.sgml
@@ -0,0 +1,41 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "../version.xml">
+]>
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <bookinfo>
+    <title>Foolib Reference Manual</title>
+    <releaseinfo>
+      for Foobar &version;
+    </releaseinfo>
+    <authorgroup>
+      <author>
+        <firstname>Jonny</firstname>
+        <surname>Example</surname>
+        <affiliation>
+          <address>
+            <email>unknown@example.com</email>
+          </address>
+        </affiliation>
+      </author>
+    </authorgroup>
+    <copyright>
+      <year>2015</year>
+      <holder>Foobar corporation holdings ltd</holder>
+    </copyright>
+  </bookinfo>
+
+  <reference id="foobar">
+    <title>Foobar library</title>
+    <partintro>
+      <para>
+        This part documents Foobar libs.
+      </para>
+    </partintro>
+    <xi:include href="xml/foo.xml"/>
+    <xi:include href="../../include/bar.xml"/>
+    <xi:include href="xml/foo-version.xml"/>
+  </reference>
+
+</book>
diff --git a/test cases/frameworks/10 gtk-doc/doc/foobar4/meson.build b/test cases/frameworks/10 gtk-doc/doc/foobar4/meson.build
new file mode 100644
index 0000000..959e507
--- /dev/null
+++ b/test cases/frameworks/10 gtk-doc/doc/foobar4/meson.build
@@ -0,0 +1,7 @@
+gnome.gtkdoc('foobar2',
+  module_version : '3.0',
+  src_dir : inc,
+  main_sgml : 'foobar-docs.sgml',
+  content_files : [docbook, version_xml],
+  install : true,
+  install_dir : 'foobar3')
diff --git a/test cases/frameworks/10 gtk-doc/doc/meson.build b/test cases/frameworks/10 gtk-doc/doc/meson.build
index 019be94..c001f89 100644
--- a/test cases/frameworks/10 gtk-doc/doc/meson.build
+++ b/test cases/frameworks/10 gtk-doc/doc/meson.build
@@ -4,30 +4,7 @@ version_xml = configure_file(input : 'version.xml.in',
                              output : 'version.xml',
                              configuration : cdata)
 
-gnome.gtkdoc('foobar',
-  src_dir : inc,
-  main_sgml : 'foobar-docs.sgml',
-  content_files : [docbook, version_xml],
-  install : true)
-
-gnome.gtkdoc('foobar2',
-  src_dir : inc,
-  main_sgml : 'foobar-docs.sgml',
-  content_files : [docbook, version_xml],
-  install : true,
-  install_dir : 'foobar2')
-
-gnome.gtkdoc('foobar',
-  module_version : '3.0',
-  src_dir : inc,
-  main_sgml : 'foobar-docs.sgml',
-  content_files : [docbook, version_xml],
-  install : true)
-
-gnome.gtkdoc('foobar2',
-  module_version : '3.0',
-  src_dir : inc,
-  main_sgml : 'foobar-docs.sgml',
-  content_files : [docbook, version_xml],
-  install : true,
-  install_dir : 'foobar3')
+subdir('foobar1')
+subdir('foobar2')
+subdir('foobar3')
+subdir('foobar4')