[gtk+/wip/meson: 171/181] build: Generate the API references (WIP)

[Emmanuele Bassi <ebassi src gnome org>]

commit 4f1326c3e4d0fd8ce6cff853d04a232f0ebee9f6
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Wed Apr 19 11:35:45 2017 +0100

    build: Generate the API references (WIP)
    
    Still a work in progress.

 docs/reference/gdk/meson.build                     |  173 ++++++++++++++++++++
 docs/reference/gsk/{gsk-docs.xml => gsk4-docs.xml} |    0
 docs/reference/gsk/meson.build                     |   61 +++++++
 docs/reference/gtk/Makefile.am                     |    2 +-
 .../reference/gtk/{gtk-docs.sgml => gtk4-docs.xml} |    0
 .../gtk/{gtk3-overrides.txt => gtk4-overrides.txt} |    0
 docs/reference/gtk/meson.build                     |   33 ++++
 docs/reference/meson.build                         |   17 ++
 docs/tools/meson.build                             |   12 ++
 meson.build                                        |    7 +
 meson_options.txt                                  |    2 +
 11 files changed, 306 insertions(+), 1 deletions(-)
---
diff --git a/docs/reference/gdk/meson.build b/docs/reference/gdk/meson.build
new file mode 100644
index 0000000..e569767
--- /dev/null
+++ b/docs/reference/gdk/meson.build
@@ -0,0 +1,173 @@
+private_headers = [
+  'gdkintl.h',
+  'gdkmarshalers.h',
+  'gdkkeysyms.h',
+  'gdkinternals.h',
+  'gdkprivate.h',
+  'gdk-private.h',
+  'gdkapplaunchcontextprivate.h',
+  'gdkcursorprivate.h',
+  'gdkdevicemanagerprivate.h',
+  'gdkdeviceprivate.h',
+  'gdkdisplaymanagerprivate.h',
+  'gdkdisplayprivate.h',
+  'gdkdndprivate.h',
+  'gdkdrawcontextprivate.h',
+  'gdkframeclockprivate.h',
+  'gdkglcontextprivate.h',
+  'gdkkeysprivate.h',
+  'gdkmonitorprivate.h',
+  'gdkscreenprivate.h',
+  'gdkseatdefaultprivate.h',
+  'gdkseatprivate.h',
+  'gdkvisualprivate.h',
+  'gdkvulkancontextprivate.h',
+  'keyname-table.h',
+  'win32',
+  'x11',
+  'quartz',
+  'broadway',
+  'wayland',
+]
+
+images = [
+  'images/rotated-text.png',
+  'images/X_cursor.png',
+  'images/arrow.png',
+  'images/based_arrow_down.png',
+  'images/based_arrow_up.png',
+  'images/boat.png',
+  'images/bogosity.png',
+  'images/bottom_left_corner.png',
+  'images/bottom_right_corner.png',
+  'images/bottom_side.png',
+  'images/bottom_tee.png',
+  'images/box_spiral.png',
+  'images/center_ptr.png',
+  'images/circle.png',
+  'images/clock.png',
+  'images/coffee_mug.png',
+  'images/cross.png',
+  'images/cross_reverse.png',
+  'images/crosshair.png',
+  'images/diamond_cross.png',
+  'images/dot.png',
+  'images/dotbox.png',
+  'images/double_arrow.png',
+  'images/draft_large.png',
+  'images/draft_small.png',
+  'images/draped_box.png',
+  'images/exchange.png',
+  'images/fleur.png',
+  'images/gobbler.png',
+  'images/gumby.png',
+  'images/hand1.png',
+  'images/hand2.png',
+  'images/heart.png',
+  'images/icon.png',
+  'images/iron_cross.png',
+  'images/left_ptr.png',
+  'images/left_side.png',
+  'images/left_tee.png',
+  'images/leftbutton.png',
+  'images/ll_angle.png',
+  'images/lr_angle.png',
+  'images/man.png',
+  'images/middlebutton.png',
+  'images/mouse.png',
+  'images/pencil.png',
+  'images/pirate.png',
+  'images/plus.png',
+  'images/question_arrow.png',
+  'images/right_ptr.png',
+  'images/right_side.png',
+  'images/right_tee.png',
+  'images/rightbutton.png',
+  'images/rtl_logo.png',
+  'images/sailboat.png',
+  'images/sb_down_arrow.png',
+  'images/sb_h_double_arrow.png',
+  'images/sb_left_arrow.png',
+  'images/sb_right_arrow.png',
+  'images/sb_up_arrow.png',
+  'images/sb_v_double_arrow.png',
+  'images/shuttle.png',
+  'images/sizing.png',
+  'images/spider.png',
+  'images/spraycan.png',
+  'images/star.png',
+  'images/target.png',
+  'images/tcross.png',
+  'images/top_left_arrow.png',
+  'images/top_left_corner.png',
+  'images/top_right_corner.png',
+  'images/top_side.png',
+  'images/top_tee.png',
+  'images/trek.png',
+  'images/ul_angle.png',
+  'images/umbrella.png',
+  'images/ur_angle.png',
+  'images/watch.png',
+  'images/xterm.png',
+  'images/alias_cursor.png',
+  'images/all_scroll_cursor.png',
+  'images/cell_cursor.png',
+  'images/col_resize_cursor.png',
+  'images/copy_cursor.png',
+  'images/crosshair_cursor.png',
+  'images/default_cursor.png',
+  'images/e_resize_cursor.png',
+  'images/ew_resize_cursor.png',
+  'images/grabbing_cursor.png',
+  'images/grab_cursor.png',
+  'images/hand_cursor.png',
+  'images/context_menu_cursor.png',
+  'images/help_cursor.png',
+  'images/move_cursor.png',
+  'images/ne_resize_cursor.png',
+  'images/nesw_resize_cursor.png',
+  'images/no_drop_cursor.png',
+  'images/not_allowed_cursor.png',
+  'images/n_resize_cursor.png',
+  'images/ns_resize_cursor.png',
+  'images/nw_resize_cursor.png',
+  'images/nwse_resize_cursor.png',
+  'images/pointer_cursor.png',
+  'images/progress_cursor.png',
+  'images/row_resize_cursor.png',
+  'images/se_resize_cursor.png',
+  'images/s_resize_cursor.png',
+  'images/sw_resize_cursor.png',
+  'images/text_cursor.png',
+  'images/vertical_text_cursor.png',
+  'images/wait_cursor.png',
+  'images/w_resize_cursor.png',
+  'images/X_cursor.png',
+  'images/zoom_in_cursor.png',
+  'images/zoom_out_cursor.png',
+]
+
+configure_file(input: 'version.xml.in', output: 'version.xml', configuration: version_conf)
+
+gnome.gtkdoc('gdk4',
+             main_xml: 'gdk4-docs.xml',
+             src_dir: [
+              join_paths(meson.source_root(), 'gdk'),
+              join_paths(meson.build_root(), 'gdk'),
+            ],
+             dependencies: libgtk_dep,
+             gobject_typesfile: 'gdk4.types',
+             scan_args: [
+               '--ignore-decorators=_GDK_EXTERN',
+              '--ignore-decorators=G_GNUC_WARN_UNUSED_RESULT',
+               '--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),
+             ],
+             html_assets: images,
+             install: true)
diff --git a/docs/reference/gsk/gsk-docs.xml b/docs/reference/gsk/gsk4-docs.xml
similarity index 100%
rename from docs/reference/gsk/gsk-docs.xml
rename to docs/reference/gsk/gsk4-docs.xml
diff --git a/docs/reference/gsk/meson.build b/docs/reference/gsk/meson.build
new file mode 100644
index 0000000..0464afb
--- /dev/null
+++ b/docs/reference/gsk/meson.build
@@ -0,0 +1,61 @@
+private_headers = [
+  'gskcairoblurprivate.h',
+  'gskcairorendererprivate.h',
+  'gskdebugprivate.h',
+  'gskgldriverprivate.h',
+  'gskglprofilerprivate.h',
+  'gskglrendererprivate.h',
+  'gskprivate.h',
+  'gskprofilerprivate.h',
+  'gskrendererprivate.h',
+  'gskrendernodeprivate.h',
+  'gskroundedrectprivate.h',
+  'gskshaderbuilderprivate.h',
+  'gsktextureprivate.h',
+  'gskvulkanblendpipelineprivate.h',
+  'gskvulkanborderpipelineprivate.h',
+  'gskvulkanboxshadowpipelineprivate.h',
+  'gskvulkanbufferprivate.h',
+  'gskvulkanclipprivate.h',
+  'gskvulkancolorpipelineprivate.h',
+  'gskvulkancommandpoolprivate.h',
+  'gskvulkaneffectpipelineprivate.h',
+  'gskvulkanimageprivate.h',
+  'gskvulkanlineargradientpipelineprivate.h',
+  'gskvulkanmemoryprivate.h',
+  'gskvulkanpipelineprivate.h',
+  'gskvulkanpushconstantsprivate.h',
+  'gskvulkanrendererprivate.h',
+  'gskvulkanrenderpassprivate.h',
+  'gskvulkanrenderprivate.h',
+  'gskvulkanshaderprivate.h',
+]
+
+images = [
+]
+
+configure_file(input: 'version.xml.in', output: 'version.xml', configuration: version_conf)
+
+gnome.gtkdoc('gsk4',
+             main_xml: 'gsk4-docs.xml',
+             src_dir: [
+              join_paths(meson.source_root(), 'gsk'),
+              join_paths(meson.build_root(), 'gsk'),
+            ],
+             dependencies: libgtk_dep,
+             gobject_typesfile: 'gsk4.types',
+             scan_args: [
+               '--ignore-decorators=_GDK_EXTERN',
+              '--ignore-decorators=G_GNUC_WARN_UNUSED_RESULT',
+               '--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=../gdk',
+             ],
+             html_assets: images,
+             install: true)
diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am
index e02fc81..9ec9fb1 100644
--- a/docs/reference/gtk/Makefile.am
+++ b/docs/reference/gtk/Makefile.am
@@ -6,7 +6,7 @@ AUTOMAKE_OPTIONS = 1.6
 DOC_MODULE=gtk4
 
 # The top-level SGML file.
-DOC_MAIN_SGML_FILE=gtk-docs.sgml
+DOC_MAIN_SGML_FILE=gtk4-docs.xml
 
 # Extra options to supply to gtkdoc-scan
 SCAN_OPTIONS=--deprecated-guards="GTK_ENABLE_BROKEN|GTK_DISABLE_DEPRECATED"
diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk4-docs.xml
similarity index 100%
rename from docs/reference/gtk/gtk-docs.sgml
rename to docs/reference/gtk/gtk4-docs.xml
diff --git a/docs/reference/gtk/gtk3-overrides.txt b/docs/reference/gtk/gtk4-overrides.txt
similarity index 100%
rename from docs/reference/gtk/gtk3-overrides.txt
rename to docs/reference/gtk/gtk4-overrides.txt
diff --git a/docs/reference/gtk/meson.build b/docs/reference/gtk/meson.build
new file mode 100644
index 0000000..4f51593
--- /dev/null
+++ b/docs/reference/gtk/meson.build
@@ -0,0 +1,33 @@
+private_headers = [
+]
+
+images = [
+]
+
+configure_file(input: 'version.xml.in', output: 'version.xml', configuration: version_conf)
+
+gnome.gtkdoc('gtk4',
+             main_xml: 'gtk4-docs.xml',
+             src_dir: [
+              join_paths(meson.source_root(), 'gtk'),
+              join_paths(meson.build_root(), 'gtk'),
+            ],
+             dependencies: libgtk_dep,
+             gobject_typesfile: 'gtk4.types',
+             scan_args: [
+               '--ignore-decorators=_GDK_EXTERN',
+              '--ignore-decorators=G_GNUC_WARN_UNUSED_RESULT',
+               '--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(gdkpixbuf_docpath),
+              '--extra-dir=../gdk',
+              '--extra-dir=../gsk',
+             ],
+             html_assets: images,
+             install: true)
diff --git a/docs/reference/meson.build b/docs/reference/meson.build
new file mode 100644
index 0000000..53458a6
--- /dev/null
+++ b/docs/reference/meson.build
@@ -0,0 +1,17 @@
+glib_prefix = dependency('glib-2.0').get_pkgconfig_variable('prefix')
+glib_docpath = join_paths(glib_prefix, 'share', 'gtk-doc', 'html')
+
+cairo_prefix = dependency('cairo-gobject').get_pkgconfig_variable('prefix')
+cairo_docpath = join_paths(cairo_prefix, 'share', 'gtk-doc', 'html', 'cairo')
+
+gdkpixbuf_prefix = dependency('gdk-pixbuf-2.0').get_pkgconfig_variable('prefix')
+gdkpixbuf_docpath = join_paths(gdkpixbuf_prefix, 'share', 'gtk-doc', 'html', 'gdk-pixbuf')
+
+docpath = join_paths(gtk_datadir, 'gtk-doc', 'html')
+
+version_conf = configuration_data()
+version_conf.set('GTK_VERSION', meson.project_version())
+
+subdir('gdk')
+subdir('gsk')
+subdir('gtk')
diff --git a/docs/tools/meson.build b/docs/tools/meson.build
new file mode 100644
index 0000000..05621ee
--- /dev/null
+++ b/docs/tools/meson.build
@@ -0,0 +1,12 @@
+if x11_enabled
+  doc_shooter_sources = [
+    'shadow.c',
+    'shooter.c',
+    'widgets.c',
+    '../../tests/gtkgears.c',
+  ]
+
+  doc_shooter = executable('doc-shooter', doc_shooter_sources,
+                           include_directories: [ confinc, gdkinc, gtkinc, testinc, ],
+                           dependencies: libgtk_dep)
+endif
diff --git a/meson.build b/meson.build
index da5505e..4dcc641 100644
--- a/meson.build
+++ b/meson.build
@@ -291,7 +291,9 @@ endif
 
 confinc = include_directories('.')
 gdkinc = include_directories('gdk')
+gskinc = include_directories('gsk')
 gtkinc = include_directories('gtk')
+testinc = include_directories('tests')
 
 glib_dep       = dependency('glib-2.0', version: glib_req)
 giounix_dep    = dependency('gio-unix-2.0', version: glib_req, required: false)
@@ -577,3 +579,8 @@ endif
 
 subdir('po')
 subdir('po-properties')
+
+if get_option('enable-documentation')
+  subdir('docs/tools')
+  subdir('docs/reference')
+endif
diff --git a/meson_options.txt b/meson_options.txt
index d23e319..f9a419d 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -24,3 +24,5 @@ option('disable-modules', type: 'boolean', value : 'false',
   description : 'Disable dynamic module loading')
 option('with-included-immodules', type: 'string', value : '',
   description : 'Build the specified input methods into gtk (comma-separated list or "all" or "none")')
+option('enable-documentation', type: 'boolean', value: 'false',
+  description : 'Build API reference and tools documentation')