[gimp] devel-docs: Introspected Python libgimp and libgimpui docs generation.

[Jehan <jehanp src gnome org>]

commit 82209920a9a5ac61044f41f37bf99d22d0b2bbd3
Author: Jehan <jehan girinstud io>
Date:   Thu Jan 21 16:31:35 2021 +0100

    devel-docs: Introspected Python libgimp and libgimpui docs generation.
    
    Based on the proposed process proposed by Akkana Peck. Thanks Akk!
    For now, it's only in the meson build, which is fairly terrible to use
    as soon as we do custom build rules. Here are the list of issues:
    
    - meson does not allow building in subdir (issue 2320 on meson tracker).
      Sure I could make several subdirs with meson in them. But here the
      future goal would be to be able to generate docs for other
      introspected languages, and maybe also other output formats (epub or
      whatnot). For this, since these are basically the same commands which
      are used, the best practice would be to have loops generating one
      target per language/format combination, reusing code rather than ugly
      copy-pasting in subdirectories' meson files).
    - custom_target() requires the output parameter to be the complete list
      of generated files. But we have more than a thousand of them. It's not
      practical. Maybe we could try to find a way to generate the list from
      the contents of the .def files which are already exhaustive and exact.
    - Install also requires the output list to be complete.
    - I temporarily have these docs not generated by default (because the
      gtk-doc option is already crazy slow as it is, making meson near
      unusable for development if it's enabled). If you want to generate the
      docs, the commands are as following (yeah I don't understand what the
      target names are for since meson does not actually create targets with
      these names, so we have to use fake output names instead):
    
    > ninja devel-docs/g-ir-docs/Gimp-python-html
    > ninja devel-docs/g-ir-docs/GimpUi-python-html

 devel-docs/g-ir-docs/meson.build | 110 +++++++++++++++++++++++++++++++++++++++
 devel-docs/meson.build           |   1 +
 meson.build                      |   3 ++
 3 files changed, 114 insertions(+)
---
diff --git a/devel-docs/g-ir-docs/meson.build b/devel-docs/g-ir-docs/meson.build
new file mode 100644
index 0000000000..d54f0af0d9
--- /dev/null
+++ b/devel-docs/g-ir-docs/meson.build
@@ -0,0 +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@' + '/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@' + '/html/Python/Gimp-' + gimp_api_version,
+      '@INPUT@'
+    ],
+    build_by_default: false)
+
+  ## 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@' + '/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@' + '/html/Python/Gimp-' + gimp_api_version,
+    ])
+
+  ## 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@' + '/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@' + '/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@' + '/html/Python/GimpUi-' + gimp_api_version,
+    ])
+
+  ## TODO: a unit test using yelp-check would be useful.
+
+endif
diff --git a/devel-docs/meson.build b/devel-docs/meson.build
index 1cf1b94b39..f6d944291d 100644
--- a/devel-docs/meson.build
+++ b/devel-docs/meson.build
@@ -30,3 +30,4 @@ subdir('libgimpmodule')
 subdir('libgimpthumb')
 subdir('libgimpwidgets')
 subdir('tools')
+subdir('g-ir-docs')
diff --git a/meson.build b/meson.build
index e0e6598e6d..ce635ce858 100644
--- a/meson.build
+++ b/meson.build
@@ -1014,6 +1014,9 @@ appstream_util = find_program('appstream-util', required: get_option('appdata-te
 # 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)
+
 # Check for vector icons
 have_vector_icons = get_option('vec-icons')
 if have_vector_icons