[gimp] devel-docs, meson: g-ir-doc option to generate introspected API docs.

[Jehan <jehanp src gnome org>]

commit eae3d47e32ed48d38ecf1e0c4412076319fa967d
Author: Jehan <jehan girinstud io>
Date:   Fri Jan 29 16:51:47 2021 +0100

    devel-docs, meson: g-ir-doc option to generate introspected API docs.
    
    Similar to the --enable-g-ir-doc option I just added on autotools. Also
    separate this option from gtk-doc as it is unrelated (not everything
    under devel-docs is related to gtk-doc!).

 devel-docs/g-ir-docs/meson.build | 202 +++++++++++++++++++--------------------
 devel-docs/meson.build           |  29 +++---
 meson.build                      |  16 ++--
 meson_options.txt                |   1 +
 4 files changed, 127 insertions(+), 121 deletions(-)
---
diff --git a/devel-docs/g-ir-docs/meson.build b/devel-docs/g-ir-docs/meson.build
index d54f0af0d9..b84553b682 100644
--- a/devel-docs/g-ir-docs/meson.build
+++ b/devel-docs/g-ir-docs/meson.build
@@ -1,110 +1,110 @@
-if gir_doc_tool.found() and yelp_build.found()
+# XXX meson does not allow building into subdir:
+# https://github.com/mesonbuild/meson/issues/2320
+# Otherwise I could use '-o', '@OUTDIR@' into following commands if
+# the `output` was subdir-able.
+gir_docs_dir = custom_target('g-ir-docs-dir',
+  depends: [ libgimp_gir, libgimpui_gir ],
+  input: [ ],
+  output: [ 'html-dirs' ],
+  command: [
+    'mkdir', '-p',
+    '@OUTDIR@' + '/pages/Python/GimpUi-' + gimp_api_version,
+    '@OUTDIR@' + '/pages/Python/Gimp-' + gimp_api_version,
+    '@OUTDIR@' + '/html/Python/GimpUi-' + gimp_api_version,
+    '@OUTDIR@' + '/html/Python/Gimp-' + gimp_api_version
+  ],
+  build_by_default: true)
 
-  # XXX meson does not allow building into subdir:
-  # https://github.com/mesonbuild/meson/issues/2320
-  # Otherwise I could use '-o', '@OUTDIR@' into following commands if
-  # the `output` was subdir-able.
-  gir_docs_dir = custom_target('g-ir-docs-dir',
-    depends: [ libgimp_gir, libgimpui_gir ],
-    input: [ ],
-    output: [ 'html-dirs' ],
-    command: [
-      'mkdir', '-p',
-      '@OUTDIR@' + '/html/Python/GimpUi-' + gimp_api_version,
-      '@OUTDIR@' + '/html/Python/Gimp-' + gimp_api_version
-    ],
-    build_by_default: false)
+# XXX `output` is bogus. g-ir-doc-tool produces a lot of output,
+# basically one page per public symbol, which is more than 1000 so
+# it's not usable. Since custom_target() requires an 'output', I could
+# just set one output such as 'index.page` as a trick, but since we
+# have another issue on subdir anyway (cf. above), I use some bogus
+# file instead. The fact the bogus file is not even created does not
+# even seem to be a problem for meson.
+# Moreover I realized that the targets listed by ninja are only the
+# output files (not the target name), so I basically ends up using
+# this field to create understandable names).
+gir_docs_python = custom_target('g-ir-Gimp-python-pages',
+  depends: [ gir_docs_dir, libgimp_gir ],
+  input: [ libgimp_gir[0] ],
+  output: [ 'Gimp-python-pages' ],
+  command: [
+    gir_doc_tool,
+    '-I', prefix / 'share/gir-1.0/',
+    '-I', meson.build_root() / 'libgimp',
+    '--language=Python',
+    '-o', '@OUTDIR@' + '/pages/Python/Gimp-' + gimp_api_version,
+    '@INPUT@'
+  ],
+  build_by_default: true)
 
-  # XXX `output` is bogus. g-ir-doc-tool produces a lot of output,
-  # basically one page per public symbol, which is more than 1000 so
-  # it's not usable. Since custom_target() requires an 'output', I could
-  # just set one output such as 'index.page` as a trick, but since we
-  # have another issue on subdir anyway (cf. above), I use some bogus
-  # file instead. The fact the bogus file is not even created does not
-  # even seem to be a problem for meson.
-  # Moreover I realized that the targets listed by ninja are only the
-  # output files (not the target name), so I basically ends up using
-  # this field to create understandable names).
-  gir_docs_python = custom_target('g-ir-Gimp-python-pages',
-    depends: [ gir_docs_dir, libgimp_gir ],
-    input: [ libgimp_gir[0] ],
-    output: [ 'Gimp-python-pages' ],
-    command: [
-      gir_doc_tool,
-      '-I', prefix / 'share/gir-1.0/',
-      '-I', meson.build_root() / 'libgimp',
-      '--language=Python',
-      '-o', '@OUTDIR@' + '/html/Python/Gimp-' + gimp_api_version,
-      '@INPUT@'
-    ],
-    build_by_default: false)
+## Gimp Module ##
 
-  ## Gimp Module ##
+gir_cache_python = custom_target('g-ir-Gimp-python-cache',
+  input: [ gir_docs_python ],
+  output: [ 'Gimp-python-cache' ],
+  command: [
+    yelp_build, 'cache',
+    '-o', '@OUTDIR@' + '/pages/Python/Gimp-' + gimp_api_version + '/index.cache',
+    '@OUTDIR@' + '/pages/Python/Gimp-' + gimp_api_version,
+  ],
+  build_by_default: true)
 
-  gir_cache_python = custom_target('g-ir-Gimp-python-cache',
-    input: [ gir_docs_python ],
-    output: [ 'Gimp-python-cache' ],
-    command: [
-      yelp_build, 'cache',
-      '-o', '@OUTDIR@' + '/html/Python/Gimp-' + gimp_api_version + '/index.cache',
-      '@OUTDIR@' + '/html/Python/Gimp-' + gimp_api_version,
-    ],
-    build_by_default: false)
+gir_html_python = custom_target('g-ir-Gimp-python-html',
+  input: [ gir_cache_python ],
+  output: [ 'Gimp-python-html' ],
+  # TODO: `output` needs to be complete for installation to work. So
+  # we need to figure out how to install the generated files (listing
+  # all of them is a crazy idea, but maybe we can generate the
+  # expected list somehow? Maybe even using the .def file which is
+  # already an exhaustive listing would be a good idea?
+  # Also where should we install exactly?
+  #install_dir: prefix / gimpdatadir / 'g-ir-docs/html/Python/Gimp',
+  #install: true,
+  command: [
+    'yelp-build', 'html',
+    '-o', '@OUTDIR@' + '/html/Python/Gimp-' + gimp_api_version,
+    '@OUTDIR@' + '/pages/Python/Gimp-' + gimp_api_version,
+  ],
+  build_by_default: true)
 
-  gir_html_python = custom_target('g-ir-Gimp-python-html',
-    input: [ gir_cache_python ],
-    output: [ 'Gimp-python-html' ],
-    # TODO: `output` needs to be complete for installation to work. So
-    # we need to figure out how to install the generated files (listing
-    # all of them is a crazy idea, but maybe we can generate the
-    # expected list somehow? Maybe even using the .def file which is
-    # already an exhaustive listing would be a good idea?
-    # Also where should we install exactly?
-    #install_dir: prefix / gimpdatadir / 'g-ir-docs/html/Python/Gimp',
-    #install: true,
-    command: [
-      'yelp-build', 'html',
-      '-o', '@OUTDIR@' + '/html/Python/Gimp-' + gimp_api_version,
-      '@OUTDIR@' + '/html/Python/Gimp-' + gimp_api_version,
-    ])
+## GimpUi module ##
 
-  ## GimpUi module ##
+gir_docs_python = custom_target('g-ir-GimpUi-python-pages',
+  depends: [ gir_docs_dir, libgimpui_gir ],
+  input: [ libgimpui_gir[0] ],
+  output: [ 'GimpUi-python-pages' ],
+  command: [
+    gir_doc_tool,
+    '-I', prefix / 'share/gir-1.0/',
+    '-I', meson.build_root() / 'libgimp',
+    '--language=Python',
+    '-o', '@OUTDIR@' + '/pages/Python/GimpUi-' + gimp_api_version,
+    '@INPUT@'
+  ],
+  build_by_default: true)
 
-  gir_docs_python = custom_target('g-ir-GimpUi-python-pages',
-    depends: [ gir_docs_dir, libgimpui_gir ],
-    input: [ libgimpui_gir[0] ],
-    output: [ 'GimpUi-python-pages' ],
-    command: [
-      gir_doc_tool,
-      '-I', prefix / 'share/gir-1.0/',
-      '-I', meson.build_root() / 'libgimp',
-      '--language=Python',
-      '-o', '@OUTDIR@' + '/html/Python/GimpUi-' + gimp_api_version,
-      '@INPUT@'
-    ],
-    build_by_default: false)
+gir_cache_python = custom_target('g-ir-GimpUi-python-cache',
+  input: [ gir_docs_python ],
+  output: [ 'GimpUi-python-cache' ],
+  command: [
+    yelp_build, 'cache',
+    '-o', '@OUTDIR@' + '/pages/Python/GimpUi-' + gimp_api_version + '/index.cache',
+    '@OUTDIR@' + '/pages/Python/GimpUi-' + gimp_api_version,
+  ],
+  build_by_default: true)
 
-  gir_cache_python = custom_target('g-ir-GimpUi-python-cache',
-    input: [ gir_docs_python ],
-    output: [ 'GimpUi-python-cache' ],
-    command: [
-      yelp_build, 'cache',
-      '-o', '@OUTDIR@' + '/html/Python/GimpUi-' + gimp_api_version + '/index.cache',
-      '@OUTDIR@' + '/html/Python/GimpUi-' + gimp_api_version,
-    ],
-    build_by_default: false)
+gir_html_python = custom_target('g-ir-GimpUi-python-html',
+  input: [ gir_cache_python ],
+  output: [ 'GimpUi-python-html' ],
+  #install_dir: prefix / gimpdatadir / 'g-ir-docs/html/Python/GimpUi',
+  #install: true,
+  command: [
+    'yelp-build', 'html',
+    '-o', '@OUTDIR@' + '/html/Python/GimpUi-' + gimp_api_version,
+    '@OUTDIR@' + '/pages/Python/GimpUi-' + gimp_api_version,
+  ],
+  build_by_default: true)
 
-  gir_html_python = custom_target('g-ir-GimpUi-python-html',
-    input: [ gir_cache_python ],
-    output: [ 'GimpUi-python-html' ],
-    #install_dir: prefix / gimpdatadir / 'g-ir-docs/html/Python/GimpUi',
-    #install: true,
-    command: [
-      'yelp-build', 'html',
-      '-o', '@OUTDIR@' + '/html/Python/GimpUi-' + gimp_api_version,
-      '@OUTDIR@' + '/html/Python/GimpUi-' + gimp_api_version,
-    ])
-
-  ## TODO: a unit test using yelp-check would be useful.
-
-endif
+## TODO: a unit test using yelp-check would be useful.
diff --git a/devel-docs/meson.build b/devel-docs/meson.build
index f6d944291d..48919e76c6 100644
--- a/devel-docs/meson.build
+++ b/devel-docs/meson.build
@@ -17,17 +17,22 @@ mkdb_args_common = [
 ]
 
 
-if get_option('gtk-doc-app')
-  subdir('app')
+if get_option('gtk-doc')
+  if get_option('gtk-doc-app')
+    subdir('app')
+  endif
+
+  subdir('libgimp')
+  subdir('libgimpbase')
+  subdir('libgimpcolor')
+  subdir('libgimpconfig')
+  subdir('libgimpmath')
+  subdir('libgimpmodule')
+  subdir('libgimpthumb')
+  subdir('libgimpwidgets')
+  subdir('tools')
 endif
 
-subdir('libgimp')
-subdir('libgimpbase')
-subdir('libgimpcolor')
-subdir('libgimpconfig')
-subdir('libgimpmath')
-subdir('libgimpmodule')
-subdir('libgimpthumb')
-subdir('libgimpwidgets')
-subdir('tools')
-subdir('g-ir-docs')
+if get_option('g-ir-doc')
+  subdir('g-ir-docs')
+endif
diff --git a/meson.build b/meson.build
index ce635ce858..4ca630274d 100644
--- a/meson.build
+++ b/meson.build
@@ -1012,10 +1012,10 @@ desktop_validate    = find_program('desktop-file-validate', required: false)
 appstream_util = find_program('appstream-util', required: get_option('appdata-test'))
 
 # Check for doc generation tools
-have_gtk_doc = get_option('gtk-doc')
-
-gir_doc_tool = find_program('g-ir-doc-tool', required: false)
-yelp_build   = find_program('yelp-build', required: false)
+if get_option('g-ir-doc')
+  gir_doc_tool = find_program('g-ir-doc-tool', required: true)
+  yelp_build   = find_program('yelp-build', required: true)
+endif
 
 # Check for vector icons
 have_vector_icons = get_option('vec-icons')
@@ -1657,10 +1657,7 @@ subdir('app-tools')
 
 # Docs
 subdir('docs')
-if have_gtk_doc
-  subdir('devel-docs')
-endif
-
+subdir('devel-docs')
 
 
 pkgconfig.generate(libgimp,
@@ -1803,6 +1800,9 @@ final_message = [
 '''  Use xvfb-run         @0@'''.format(xvfb_run.found()),
 '''  Test appdata         @0@'''.format(appstream_util.found()),
 '',
+'''Documentation:''',
+'''  GObject Introspection: @0@'''.format(get_option('g-ir-doc')),
+'',
 '''Bug report URL: @0@'''.format(bug_report_url),
 ]
 
diff --git a/meson_options.txt b/meson_options.txt
index 33bdd1aa6b..7b6ad78045 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -51,6 +51,7 @@ option('headless-tests',    type: 'feature', value: 'auto', description: 'Use xv
 
 option('gtk-doc',           type: 'boolean', value: true,   description: 'Build developer documentation')
 option('gtk-doc-app',       type: 'boolean', value: false,  description: 'Build developer documentation for 
app')
+option('g-ir-doc',          type: 'boolean', value: false,  description: 'Build developer documentation for 
introspected API')
 
 option('linux-input',       type: 'feature', value: 'auto', description: 'Linux input event controller 
module')
 option('vec-icons',         type: 'boolean', value: true,   description: 'Use vector icons rather than 
raster ones')