[pango/gi-docs: 25/47] Generate Pango API docs with gi-docgen

[Matthias Clasen <matthiasc src gnome org>]

commit 5a2292e611157a8be768047f6db9e4dfcc6ebd8e
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Feb 10 16:49:26 2021 -0500

    Generate Pango API docs  with gi-docgen
    
    Stop using gtk-doc, and switch to gi-docgen.
    
    The gi-docgen tool generates API references through the introspection
    data, which has various benefits:
    
     - it does not parse C code
     - it does not generate and run C code to introspect types at build time
     - it does not present a different API from the one we're exporting
    
    Additionally, gi-docgen:
    
     - does not generate DocBook XML in order to generate HTML
     - does not go through xsltproc
     - parses proper Markdown
    
    Which makes it markedly faster than gtk-doc has ever been.

 docs/meson.build | 183 +++++++++++++++++++++++++++++++------------------------
 meson.build      |   4 ++
 2 files changed, 108 insertions(+), 79 deletions(-)
---
diff --git a/docs/meson.build b/docs/meson.build
index e847a34f..547995a8 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -1,97 +1,122 @@
-subdir('xml')
+gidocgen = find_program('gi-docgen', required: get_option('gtk_doc'))
 
-version_xml_conf = configuration_data()
-version_xml_conf.set('PANGO_VERSION', meson.project_version())
-configure_file(input: 'version.xml.in',
-               output: 'version.xml',
-               configuration: version_xml_conf)
-
-private_headers = [
-  'pangocairo-private.h',
-  'pangocairo-fc-private.h',
-  'pangocairo-fc.h',
-  'pangocairo-win32.h',
-  'pangocairo-atsui.h',
-  'pango-coverage-private.h',
-  'pango-color-table.h',
-  'pango-emoji-private.h',
-  'pango-font-private.h',
-  'pango-fontmap-private.h',
-  'pango-fontset-private.h',
-  'pango-impl-utils.h',
-  'pango-glyph-item-private.h',
-  'pango-layout-private.h',
-  'pango-script-table.h',
-  'pango-script-private.h',
-  'pango-utils-private.h',
-  'pangofc-private.h',
-  'pangofc-fontmap-private.h',
-  'pangoft2-private.h',
-  'pangowin32-private.h',
-  'pangoatsui-private.h',
-  'pangoxft-private.h',
-  'pango-ot-private.h',
-  'pango-script-lang-table.h',
-  'pango-language-sample-table.h',
-  'pangocoretext-private.h',
-]
-
-content_files = [
-  'pango_markup.sgml',
-  'version.xml',
-]
-
-html_images = [
+pango_content_files = [
+  'pango_rendering.md',
+  'pango_fonts.md',
+  'pango_markup.md',
+  'pango_bidi.md',
   'layout.png',
   'pipeline.png',
-  'rotated-text.png',
   'rects1.png',
   'rects2.png',
+  'rects3.png',
 ]
 
-docdeps = [ libpango_dep ]
+custom_target('pango-doc',
+  input: pango_gir[0],
+  output: 'Pango',
+  command: [
+    gidocgen,
+    'generate',
+    '--add-include-path=@0@'.format(meson.current_source_dir() / '../pango'),
+    '--config=@0@'.format(meson.current_source_dir() / 'pango.toml'),
+    '--output-dir=@OUTPUT@',
+    '--content-dir=@0@'.format(meson.current_source_dir()),
+    '@INPUT@',
+  ],
+  depend_files: [ 'pango.toml', pango_content_files],
+  build_by_default: true,
+)
 
 if build_pangoft2
-  docdeps += libpangoft2_dep
+  custom_target('pangoft-doc',
+    input: pangoft2_gir[0],
+    output: 'PangoFT2',
+    command: [
+      gidocgen,
+      'generate',
+      '--add-include-path=@0@'.format(meson.current_source_dir() / '../pango'),
+      '--config=@0@'.format(meson.current_source_dir() / 'pangoft2.toml'),
+      '--output-dir=@OUTPUT@/..',
+      '--content-dir=@0@'.format(meson.current_source_dir()),
+      '@INPUT@',
+    ],
+    depend_files: [ 'pangoft2.toml' ],
+    build_by_default: true,
+  )
 endif
 
 if xft_dep.found() and fontconfig_dep.found()
-  docdeps += libpangoxft_dep
+  custom_target('pangoxft-doc',
+    input: pangoxft_gir[0],
+    output: 'PangoXft',
+    command: [
+      gidocgen,
+      'generate',
+      '--add-include-path=@0@'.format(meson.current_source_dir() / '../pango'),
+      '--config=@0@'.format(meson.current_source_dir() / 'pangoxft.toml'),
+      '--output-dir=@OUTPUT@/..',
+      '--content-dir=@0@'.format(meson.current_source_dir()),
+      '@INPUT@',
+    ],
+    depend_files: [ 'pangoxft.toml' ],
+    build_by_default: true,
+  )
 endif
 
 if cairo_dep.found()
-  docdeps += libpangocairo_dep
+  pango_cairo_content_files = [
+    'pango_cairo.md',
+    'rotated-text.png',
+  ]
+
+  custom_target('pangocairo-doc',
+    input: pangocairo_gir[0],
+    output: 'PangoCairo',
+    command: [
+      gidocgen,
+      'generate',
+      '--add-include-path=@0@'.format(meson.current_source_dir() / '../pango'),
+      '--config=@0@'.format(meson.current_source_dir() / 'pangocairo.toml'),
+      '--output-dir=@OUTPUT@/..',
+      '--content-dir=@0@'.format(meson.current_source_dir()),
+      '@INPUT@',
+    ],
+    depend_files: [ 'pangocairo.toml', pango_cairo_content_files ],
+    build_by_default: true,
+  )
 endif
 
-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')
-docpath = join_paths(pango_datadir, 'gtk-doc', 'html')
+custom_target('pangoot-doc',
+  input: pangoot_gir[0],
+  output: 'PangoOT',
+  command: [
+    gidocgen,
+    'generate',
+    '--add-include-path=@0@'.format(meson.current_source_dir() / '../pango'),
+    '--config=@0@'.format(meson.current_source_dir() / 'pangoot.toml'),
+    '--output-dir=@OUTPUT@/..',
+    '--content-dir=@0@'.format(meson.current_source_dir()),
+    '@INPUT@',
+  ],
+  depend_files: [ 'pangoot.toml' ],
+  build_by_default: true,
+)
 
-gnome.gtkdoc('pango',
-             main_xml: 'pango-docs.sgml',
-             src_dir: [
-               pango_inc,
-             ],
-             dependencies: docdeps,
-             gobject_typesfile: configure_file(input: 'pango.types.in',
-                                               output: 'pango.types',
-                                               configuration: pango_conf),
-             scan_args: [
-               '--deprecated-guards=PANGO_DISABLE_DEPRECATED',
-               '--ignore-decorators=_PANGO_EXTERN',
-               '--ignore-headers=' + ' '.join(private_headers),
-             ],
-             mkdb_args: [
-               '--sgml-mode',
-               '--output-format=xml',
-             ],
-             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(cairo_docpath, 'cairo')),
-             ],
-             html_assets: html_images,
-             install: true)
+if fontconfig_dep.found()
+  custom_target('pangofc-doc',
+    input: pangofc_gir[0],
+    output: 'PangoFC',
+    command: [
+      gidocgen,
+      'generate',
+      '--add-include-path=@0@'.format(meson.current_source_dir() / '../pango'),
+      '--config=@0@'.format(meson.current_source_dir() / 'pangofc.toml'),
+      '--output-dir=@OUTPUT@/..',
+      '--content-dir=@0@'.format(meson.current_source_dir()),
+      '@INPUT@',
+    ],
+    depend_files: [ 'pangofc.toml' ],
+    build_by_default: true,
+  )
+endif
diff --git a/meson.build b/meson.build
index 28d9c9ba..f9e63347 100644
--- a/meson.build
+++ b/meson.build
@@ -585,6 +585,10 @@ libsysprof_capture_dep = dependency('sysprof-capture-4',
 pango_conf.set('HAVE_SYSPROF', libsysprof_capture_dep.found())
 pango_deps += libsysprof_capture_dep
 
+gidocgen_dep = dependency('gi-docgen', version: '>= 2021.1',
+                          fallback: ['gi-docgen', 'dummy_dep'],
+                          required: get_option('gtk_doc'))
+
 gnome = import('gnome')
 pkgconfig = import('pkgconfig')