From 1c1bce40949492a6772470385aa76151500a4dac Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Tue, 27 Apr 2021 12:08:52 +0100 Subject: [PATCH] meson: Build the API reference The Meson build system should build the API reference using gtk-doc, like the Autotools build does. The option is called `gtk_doc`, which matches the existing practices in various projects using Meson and gtk-doc. --- doc/public/meson.build | 157 ++++++++++++++++++++++++++++++++++++++ doc/public/version.xml.in | 1 + meson.build | 9 +++ meson_options.txt | 4 + 4 files changed, 171 insertions(+) create mode 100644 doc/public/meson.build create mode 100644 doc/public/version.xml.in diff --git a/doc/public/meson.build b/doc/public/meson.build new file mode 100644 index 000000000..2c27105b4 --- /dev/null +++ b/doc/public/meson.build @@ -0,0 +1,157 @@ +gnome = import('gnome') + +ignore_headers = [ + # Sub-directories + 'drm', + 'win32', + + # Internal headers + 'cairoint.h', + 'cairo-features.h', + 'cairo-features-win32.h', + + # Inlined API + 'cairo-box-inline.h', + 'cairo-clip-inline.h', + 'cairo-combsort-inline.h', + 'cairo-contour-inline.h', + 'cairo-error-inline.h', + 'cairo-image-surface-inline.h', + 'cairo-line-inline.h', + 'cairo-list-inline.h', + 'cairo-pattern-inline.h', + 'cairo-recording-surface-inline.h', + 'cairo-surface-inline.h', + 'cairo-surface-observer-inline.h', + 'cairo-surface-snapshot-inline.h', + 'cairo-surface-subsurface-inline.h', + + # Private headers + 'cairo-analysis-surface-private.h', + 'cairo-arc-private.h', + 'cairo-array-private.h', + 'cairo-atomic-private.h', + 'cairo-backend-private.h', + 'cairo-boxes-private.h', + 'cairo-cache-private.h', + 'cairo-clip-private.h', + 'cairo-compiler-private.h', + 'cairo-composite-rectangles-private.h', + 'cairo-compositor-private.h', + 'cairo-contour-private.h', + 'cairo-damage-private.h', + 'cairo-default-context-private.h', + 'cairo-deprecated.h', + 'cairo-device-private.h', + 'cairo-error-private.h', + 'cairo-fixed-private.h', + 'cairo-fixed-type-private.h', + 'cairo-fontconfig-private.h', + 'cairo-freed-pool-private.h', + 'cairo-freelist-private.h', + 'cairo-freelist-type-private.h', + 'cairo-ft-private.h', + 'cairo-gstate-private.h', + 'cairo-hash-private.h', + 'cairo-image-info-private.h', + 'cairo-image-surface-private.h', + 'cairo-line-private.h', + 'cairo-list-private.h', + 'cairo-malloc-private.h', + 'cairo-mempool-private.h', + 'cairo-mutex-impl-private.h', + 'cairo-mutex-list-private.h', + 'cairo-mutex-private.h', + 'cairo-mutex-type-private.h', + 'cairo-output-stream-private.h', + 'cairo-paginated-private.h', + 'cairo-paginated-surface-private.h', + 'cairo-path-fixed-private.h', + 'cairo-path-private.h', + 'cairo-pattern-private.h', + 'cairo-pdf-operators-private.h', + 'cairo-pdf-shading-private.h', + 'cairo-pdf-surface-private.h', + 'cairo-pixman-private.h', + 'cairo-private.h', + 'cairo-ps-surface-private.h', + 'cairo-quartz-private.h', + 'cairo-recording-surface-private.h', + 'cairo-reference-count-private.h', + 'cairo-region-private.h', + 'cairo-rtree-private.h', + 'cairo-scaled-font-private.h', + 'cairo-scaled-font-subsets-private.h', + 'cairo-script-private.h', + 'cairo-slope-private.h', + 'cairo-spans-compositor-private.h', + 'cairo-spans-private.h', + 'cairo-stroke-dash-private.h', + 'cairo-surface-backend-private.h', + 'cairo-surface-clipper-private.h', + 'cairo-surface-fallback-private.h', + 'cairo-surface-observer-private.h', + 'cairo-surface-offset-private.h', + 'cairo-surface-private.h', + 'cairo-surface-snapshot-private.h', + 'cairo-surface-subsurface-private.h', + 'cairo-surface-wrapper-private.h', + 'cairo-svg-surface-private.h', + 'cairo-tag-attributes-private.h', + 'cairo-tag-stack-private.h', + 'cairo-tee-surface-private.h', + 'cairo-time-private.h', + 'cairo-traps-private.h', + 'cairo-tristrip-private.h', + 'cairo-truetype-subset-private.h', + 'cairo-type1-private.h', + 'cairo-type3-glyph-surface-private.h', + 'cairo-types-private.h', + 'cairo-user-font-private.h', + 'cairo-wideint-private.h', + 'cairo-wideint-type-private.h', + 'cairo-xcb-private.h', + 'cairo-xlib-private.h', + 'cairo-xlib-surface-private.h', + 'cairo-xlib-xrender-private.h', + 'test-compositor-surface-private.h', +] + +ignore_decorators = [ + 'cairo_public', + 'cairo_private', +] + +docpath = get_option('prefix') / get_option('datadir') / 'gtk-doc/html' +version_conf = configuration_data() +version_conf.set('CAIRO_VERSION', meson.project_version()) +configure_file( + input: 'version.xml.in', + output: 'version.xml', + configuration: version_conf +) + +gnome.gtkdoc('cairo', + main_xml: 'cairo-docs.xml', + namespace: 'cairo', + mode: 'sgml', + src_dir: doc_srcdir, + dependencies: libcairo_dep, + scan_args: [ + '--ignore-decorators=' + '|'.join(ignore_decorators), + '--ignore-headers=' + ' '.join(ignore_headers), + ], + content_files: [ + 'language-bindings.xml', + ], + expand_content_files: [ + 'language-bindings.xml', + ], + html_assets: [ + ], + fixxref_args: [ + '--html-dir=' + docpath, + ], + install: true, + check: true, +) diff --git a/doc/public/version.xml.in b/doc/public/version.xml.in new file mode 100644 index 000000000..6bd185791 --- /dev/null +++ b/doc/public/version.xml.in @@ -0,0 +1 @@ +@CAIRO_VERSION@ diff --git a/meson.build b/meson.build index b159b4071..8098261ff 100644 --- a/meson.build +++ b/meson.build @@ -862,6 +862,14 @@ if not get_option('tests').disabled() and feature_conf.get('CAIRO_HAS_PNG_FUNCTI subdir('test') endif +if get_option('gtk_doc') + if not meson.version().version_compare('>=0.52.0') + error('Building documentation requires Meson >= 0.52.0.') + endif + doc_srcdir = include_directories('src') + subdir('doc/public') +endif + configure_file(output: 'config.h', configuration: conf) foreach feature: built_features @@ -931,5 +939,6 @@ if meson.version().version_compare('>= 0.53') summary({ 'cairo-trace:': conf.get('CAIRO_HAS_TRACE', 0) == 1, 'cairo-script-interpreter': feature_conf.get('CAIRO_HAS_INTERPRETER', 0) == 1, + 'API reference': get_option('gtk_doc'), }, section: 'Features and Utilities', bool_yn: true) endif diff --git a/meson_options.txt b/meson_options.txt index ff11fe7ed..30f6e1df8 100644 --- a/meson_options.txt +++ b/meson_options.txt @@ -30,6 +30,10 @@ option('gtk2-utils', type : 'feature', value : 'disabled') option('glib', type : 'feature', value : 'auto') option('spectre', type : 'feature', value : 'auto') +# Documentation +option('gtk_doc', type : 'boolean', value : false, + description: 'Build the Cairo API reference (depends on gtk-doc)') + # FIXME: implement these to avoid automagic #option('egl', type : 'feature', value : 'auto') #option('glx', type : 'feature', value : 'auto') -- 2.34.1