documentation: Generate API references with gi-docgen

gtk-doc support was taken out about six years ago, but never replaced.
Add support for the newer gi-docgen, which should hopefully encourage
both C and GJS users of these libraries to improve the reference.

Part-of: <https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/2248>
This commit is contained in:
Andy Holmes 2022-01-19 12:26:30 -08:00
parent dea9f8bbfe
commit b7ea424605
18 changed files with 485 additions and 0 deletions

View File

@ -0,0 +1,39 @@
[library]
version = "@version@"
browse_url = "https://gitlab.gnome.org/GNOME/mutter/"
repository_url = "https://gitlab.gnome.org/GNOME/mutter.git"
website_url = "https://blogs.gnome.org/shell-dev/"
docs_url = "https://docs.gtk.org/"
authors = "Mutter Development Team"
license = "GPL-2.0-or-later"
description = "The Clutter Accessibility Implementation Library"
dependencies = [ "GObject-2.0", "Atk-1.0" ]
devhelp = true
search_index = true
[dependencies."GObject-2.0"]
name = "GObject"
description = "The base type system library"
docs_url = "https://docs.gtk.org/gobject/"
[dependencies."Atk-1.0"]
name = "Atk"
description = "The Accessibility toolkit"
docs_url = "https://docs.gtk.org/atk/"
[theme]
name = "basic"
show_index_summary = true
show_class_hierarchy = true
[source-location]
base_url = "https://gitlab.gnome.org/GNOME/mutter/-/blob/@vcs_tag@/"
[extra]
# The same order will be used when generating the index
content_files = [
]
content_images = [
]
urlmap_file = "urlmap.js"

View File

@ -0,0 +1,33 @@
cally_toml = configure_file(
input: 'cally.toml.in',
output: 'cally.toml',
configuration: toml_conf,
install: true,
install_dir: docs_dir / 'cally',
)
custom_target('cally-doc',
input: [ cally_toml, libmutter_cally_gir[0] ],
output: 'cally',
command: [
gidocgen,
'generate',
gidocgen_common_args,
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../cogl/cogl'),
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../cogl/cogl-pango'),
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../clutter/clutter'),
'--config=@INPUT0@',
'--output-dir=@OUTPUT@',
'--content-dir=@0@'.format(meson.current_source_dir()),
'@INPUT1@',
],
depends: [
libmutter_cogl_gir[0],
libmutter_cogl_pango_gir[0],
libmutter_clutter_gir[0],
],
build_by_default: true,
install: true,
install_dir: docs_dir,
)

View File

@ -0,0 +1,15 @@
// SPDX-FileCopyrightText: 2021 GNOME Foundation
// SPDX-License-Identifier: LGPL-2.1-or-later
// A map between namespaces and base URLs for their online documentation
baseURLs = [
[ 'GLib', 'https://docs.gtk.org/glib/' ],
[ 'GObject', 'https://docs.gtk.org/gobject/' ],
[ 'Gio', 'https://docs.gtk.org/gio/' ],
[ 'Atk', 'https://docs.gtk.org/atk/' ],
[ 'Gdk', 'https://docs.gtk.org/gdk3/' ],
[ 'Gtk', 'https://docs.gtk.org/gtk3/' ],
[ 'Pango', 'https://docs.gtk.org/Pango/' ],
[ 'PangoCairo', 'https://docs.gtk.org/PangoCairo/' ],
[ 'GdkPixbuf', 'https://docs.gtk.org/gdk-pixbuf/' ],
]

View File

@ -0,0 +1,44 @@
[library]
version = "@version@"
browse_url = "https://gitlab.gnome.org/GNOME/mutter/"
repository_url = "https://gitlab.gnome.org/GNOME/mutter.git"
website_url = "https://blogs.gnome.org/shell-dev/"
docs_url = "https://docs.gtk.org/"
authors = "Mutter Development Team"
license = "GPL-2.0-or-later"
description = "An OpenGL based 'interactive canvas' library"
dependencies = [ "GObject-2.0", "cairo-1.0", "Atk-1.0" ]
devhelp = true
search_index = true
[dependencies."GObject-2.0"]
name = "GObject"
description = "The base type system library"
docs_url = "https://docs.gtk.org/gobject/"
[dependencies."cairo-1.0"]
name = "Cairo"
description = "A 2D graphics library with support for multiple output devices"
docs_url = "https://www.cairographics.org/manual/"
[dependencies."Atk-1.0"]
name = "Atk"
description = "The Accessibility toolkit"
docs_url = "https://docs.gtk.org/atk/"
[theme]
name = "basic"
show_index_summary = true
show_class_hierarchy = true
[source-location]
base_url = "https://gitlab.gnome.org/GNOME/mutter/-/blob/@vcs_tag@/"
[extra]
# The same order will be used when generating the index
content_files = [
]
content_images = [
]
urlmap_file = "urlmap.js"

View File

@ -0,0 +1,31 @@
clutter_toml = configure_file(
input: 'clutter.toml.in',
output: 'clutter.toml',
configuration: toml_conf,
install: true,
install_dir: docs_dir / 'clutter',
)
custom_target('clutter-doc',
input: [ clutter_toml, libmutter_clutter_gir[0] ],
output: 'clutter',
command: [
gidocgen,
'generate',
gidocgen_common_args,
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../cogl/cogl'),
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../cogl/cogl-pango'),
'--config=@INPUT0@',
'--output-dir=@OUTPUT@',
'--content-dir=@0@'.format(meson.current_source_dir()),
'@INPUT1@',
],
depends: [
libmutter_cogl_pango_gir[0],
libmutter_cogl_gir[0],
],
build_by_default: true,
install: true,
install_dir: docs_dir,
)

View File

@ -0,0 +1,15 @@
// SPDX-FileCopyrightText: 2021 GNOME Foundation
// SPDX-License-Identifier: LGPL-2.1-or-later
// A map between namespaces and base URLs for their online documentation
baseURLs = [
[ 'GLib', 'https://docs.gtk.org/glib/' ],
[ 'GObject', 'https://docs.gtk.org/gobject/' ],
[ 'Gio', 'https://docs.gtk.org/gio/' ],
[ 'Atk', 'https://docs.gtk.org/atk/' ],
[ 'Gdk', 'https://docs.gtk.org/gdk3/' ],
[ 'Gtk', 'https://docs.gtk.org/gtk3/' ],
[ 'Pango', 'https://docs.gtk.org/Pango/' ],
[ 'PangoCairo', 'https://docs.gtk.org/PangoCairo/' ],
[ 'GdkPixbuf', 'https://docs.gtk.org/gdk-pixbuf/' ],
]

View File

@ -0,0 +1,44 @@
[library]
version = "@version@"
browse_url = "https://gitlab.gnome.org/GNOME/mutter/"
repository_url = "https://gitlab.gnome.org/GNOME/mutter.git"
website_url = "https://blogs.gnome.org/shell-dev/"
docs_url = "https://docs.gtk.org/"
authors = "Mutter Development Team"
license = "GPL-2.0-or-later"
description = "A Low Level GPU Graphics and Utilities API"
dependencies = [ "GObject-2.0", "Pango-1.0", "PangoCairo-1.0" ]
devhelp = true
search_index = true
[dependencies."GObject-2.0"]
name = "GObject"
description = "The base type system library"
docs_url = "https://docs.gtk.org/gobject/"
[dependencies."Pango-1.0"]
name = "Pango"
description = "Text shaping and rendering"
docs_url = "https://docs.gtk.org/Pango/"
[dependencies."PangoCairo-1.0"]
name = "PangoCairo"
description = "Cairo support for Pango"
docs_url = "https://docs.gtk.org/PangoCairo/"
[theme]
name = "basic"
show_index_summary = true
show_class_hierarchy = true
[source-location]
base_url = "https://gitlab.gnome.org/GNOME/mutter/-/blob/@vcs_tag@/"
[extra]
# The same order will be used when generating the index
content_files = [
]
content_images = [
]
urlmap_file = "urlmap.js"

View File

@ -0,0 +1,29 @@
cogl_pango_toml = configure_file(
input: 'cogl-pango.toml.in',
output: 'cogl-pango.toml',
configuration: toml_conf,
install: true,
install_dir: docs_dir / 'cogl-pango',
)
custom_target('cogl-pango-doc',
input: [ cogl_pango_toml, libmutter_cogl_pango_gir[0] ],
output: 'cogl-pango',
command: [
gidocgen,
'generate',
gidocgen_common_args,
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../cogl/cogl'),
'--config=@INPUT0@',
'--output-dir=@OUTPUT@',
'--content-dir=@0@'.format(meson.current_source_dir()),
'@INPUT1@',
],
depends: [
libmutter_cogl_gir[0],
],
build_by_default: true,
install: true,
install_dir: docs_dir,
)

View File

@ -0,0 +1,15 @@
// SPDX-FileCopyrightText: 2021 GNOME Foundation
// SPDX-License-Identifier: LGPL-2.1-or-later
// A map between namespaces and base URLs for their online documentation
baseURLs = [
[ 'GLib', 'https://docs.gtk.org/glib/' ],
[ 'GObject', 'https://docs.gtk.org/gobject/' ],
[ 'Gio', 'https://docs.gtk.org/gio/' ],
[ 'Atk', 'https://docs.gtk.org/atk/' ],
[ 'Gdk', 'https://docs.gtk.org/gdk3/' ],
[ 'Gtk', 'https://docs.gtk.org/gtk3/' ],
[ 'Pango', 'https://docs.gtk.org/Pango/' ],
[ 'PangoCairo', 'https://docs.gtk.org/PangoCairo/' ],
[ 'GdkPixbuf', 'https://docs.gtk.org/gdk-pixbuf/' ],
]

View File

@ -0,0 +1,44 @@
[library]
version = "@version@"
browse_url = "https://gitlab.gnome.org/GNOME/mutter/"
repository_url = "https://gitlab.gnome.org/GNOME/mutter.git"
website_url = "https://blogs.gnome.org/shell-dev/"
docs_url = "https://docs.gtk.org/"
authors = "Mutter Development Team"
license = "GPL-2.0-or-later"
description = "A Low Level GPU Graphics and Utilities API"
dependencies = [ "GObject-2.0", "Graphene-1.0", "cairo-1.0" ]
devhelp = true
search_index = true
[dependencies."GObject-2.0"]
name = "GObject"
description = "The base type system library"
docs_url = "https://docs.gtk.org/gobject/"
[dependencies."Graphene-1.0"]
name = "Graphene"
description = "A thin layer of mathematical types for 3D libraries"
docs_url = "https://ebassi.github.io/graphene/docs"
[dependencies."cairo-1.0"]
name = "Cairo"
description = "A 2D graphics library with support for multiple output devices"
docs_url = "https://www.cairographics.org/manual/"
[theme]
name = "basic"
show_index_summary = true
show_class_hierarchy = true
[source-location]
base_url = "https://gitlab.gnome.org/GNOME/mutter/-/blob/@vcs_tag@/"
[extra]
# The same order will be used when generating the index
content_files = [
]
content_images = [
]
urlmap_file = "urlmap.js"

View File

@ -0,0 +1,25 @@
cogl_toml = configure_file(
input: 'cogl.toml.in',
output: 'cogl.toml',
configuration: toml_conf,
install: true,
install_dir: docs_dir / 'cogl',
)
custom_target('cogl-doc',
input: [ cogl_toml, libmutter_cogl_gir[0] ],
output: 'cogl',
command: [
gidocgen,
'generate',
gidocgen_common_args,
'--config=@INPUT0@',
'--output-dir=@OUTPUT@',
'--content-dir=@0@'.format(meson.current_source_dir()),
'@INPUT1@',
],
build_by_default: true,
install: true,
install_dir: docs_dir,
)

View File

@ -0,0 +1,15 @@
// SPDX-FileCopyrightText: 2021 GNOME Foundation
// SPDX-License-Identifier: LGPL-2.1-or-later
// A map between namespaces and base URLs for their online documentation
baseURLs = [
[ 'GLib', 'https://docs.gtk.org/glib/' ],
[ 'GObject', 'https://docs.gtk.org/gobject/' ],
[ 'Gio', 'https://docs.gtk.org/gio/' ],
[ 'Atk', 'https://docs.gtk.org/atk/' ],
[ 'Gdk', 'https://docs.gtk.org/gdk3/' ],
[ 'Gtk', 'https://docs.gtk.org/gtk3/' ],
[ 'Pango', 'https://docs.gtk.org/Pango/' ],
[ 'PangoCairo', 'https://docs.gtk.org/PangoCairo/' ],
[ 'GdkPixbuf', 'https://docs.gtk.org/gdk-pixbuf/' ],
]

27
doc/reference/meson.build Normal file
View File

@ -0,0 +1,27 @@
if not have_introspection
error('API reference requires introspection.')
endif
toml_conf = configuration_data()
toml_conf.set('version', libmutter_api_version)
toml_conf.set('vcs_tag', 'main')
gidocgen = find_program('gi-docgen')
gidocgen_common_args = [
'--quiet',
'--no-namespace-dir',
]
if get_option('werror')
gidocgen_common_args += ['--fatal-warnings']
endif
docs_dir = pkgdatadir / 'doc'
subdir('cally')
subdir('clutter')
subdir('cogl')
subdir('cogl-pango')
subdir('meta')

View File

@ -0,0 +1,34 @@
meta_toml = configure_file(
input: 'meta.toml.in',
output: 'meta.toml',
configuration: toml_conf,
install: true,
install_dir: docs_dir / 'meta',
)
custom_target('meta-doc',
input: [ meta_toml, libmutter_gir[0] ],
output: 'meta',
command: [
gidocgen,
'generate',
gidocgen_common_args,
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../clutter/clutter'),
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../cogl/cogl'),
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../cogl/cogl-pango'),
'--config=@INPUT0@',
'--output-dir=@OUTPUT@',
'--content-dir=@0@'.format(meson.current_source_dir()),
'@INPUT1@',
],
depends: [
libmutter_clutter_gir[0],
libmutter_cally_gir[0],
libmutter_cogl_pango_gir[0],
libmutter_cogl_gir[0],
],
build_by_default: true,
install: true,
install_dir: docs_dir,
)

View File

@ -0,0 +1,44 @@
[library]
version = "@version@"
browse_url = "https://gitlab.gnome.org/GNOME/mutter/"
repository_url = "https://gitlab.gnome.org/GNOME/mutter.git"
website_url = "https://blogs.gnome.org/shell-dev/"
docs_url = "https://docs.gtk.org/"
authors = "Mutter Development Team"
license = "GPL-2.0-or-later"
description = "The Mutter display server, window manager and compositor library"
dependencies = [ "GObject-2.0", "Gdk-3.0", "Gtk-3.0" ]
devhelp = true
search_index = true
[dependencies."GObject-2.0"]
name = "GObject"
description = "The base type system library"
docs_url = "https://docs.gtk.org/gobject/"
[dependencies."Gdk-3.0"]
name = "GDK"
description = "The GTK windowing system abstraction"
docs_url = "https://docs.gtk.org/gdk3/"
[dependencies."Gtk-3.0"]
name = "GTK"
description = "The GTK toolkit"
docs_url = "https://docs.gtk.org/gtk3/"
[theme]
name = "basic"
show_index_summary = true
show_class_hierarchy = true
[source-location]
base_url = "https://gitlab.gnome.org/GNOME/mutter/-/blob/@vcs_tag@/"
[extra]
# The same order will be used when generating the index
content_files = [
]
content_images = [
]
urlmap_file = "urlmap.js"

View File

@ -0,0 +1,15 @@
// SPDX-FileCopyrightText: 2021 GNOME Foundation
// SPDX-License-Identifier: LGPL-2.1-or-later
// A map between namespaces and base URLs for their online documentation
baseURLs = [
[ 'GLib', 'https://docs.gtk.org/glib/' ],
[ 'GObject', 'https://docs.gtk.org/gobject/' ],
[ 'Gio', 'https://docs.gtk.org/gio/' ],
[ 'Atk', 'https://docs.gtk.org/atk/' ],
[ 'Gdk', 'https://docs.gtk.org/gdk3/' ],
[ 'Gtk', 'https://docs.gtk.org/gtk3/' ],
[ 'Pango', 'https://docs.gtk.org/Pango/' ],
[ 'PangoCairo', 'https://docs.gtk.org/PangoCairo/' ],
[ 'GdkPixbuf', 'https://docs.gtk.org/gdk-pixbuf/' ],
]

View File

@ -265,6 +265,12 @@ if have_introspection
]
endif
have_documentation = get_option('docs')
if have_documentation
gidocgen_dep = dependency('gi-docgen', version: '>= 2021.1',
fallback: ['gi-docgen', 'dummy_dep'])
endif
have_tests = get_option('tests')
have_core_tests = false
have_cogl_tests = false
@ -553,6 +559,9 @@ subdir('data')
subdir('src')
subdir('po')
subdir('doc/man')
if have_documentation
subdir('doc/reference')
endif
meson.add_install_script('meson/meson-postinstall.sh')
meson.add_dist_script('meson/check-version.py', meson.project_version(), 'NEWS')
@ -579,6 +588,7 @@ summary('Wacom', have_libwacom, section: 'Options')
summary('SM', have_sm, section: 'Options')
summary('Startup notification', have_startup_notification, section: 'Options')
summary('Introspection', have_introspection, section: 'Options')
summary('Documentation', have_documentation, section: 'Options')
summary('Profiler', have_profiler, section: 'Options')
summary('Xwayland initfd', have_xwayland_initfd, section: 'Options')
summary('Xwayland listenfd', have_xwayland_listenfd, section: 'Options')

View File

@ -111,6 +111,12 @@ option('introspection',
description: 'Enable GObject introspection'
)
option('docs',
type: 'boolean',
value: false,
description: 'Enable gi-docgen documentation'
)
option('cogl_tests',
type: 'boolean',
value: true,