From b7ea424605d25020c532e4bcff80f3c1b35cb307 Mon Sep 17 00:00:00 2001 From: Andy Holmes Date: Wed, 19 Jan 2022 12:26:30 -0800 Subject: [PATCH] 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: --- doc/reference/cally/cally.toml.in | 39 ++++++++++++++++++ doc/reference/cally/meson.build | 33 ++++++++++++++++ doc/reference/cally/urlmap.js | 15 +++++++ doc/reference/clutter/clutter.toml.in | 44 +++++++++++++++++++++ doc/reference/clutter/meson.build | 31 +++++++++++++++ doc/reference/clutter/urlmap.js | 15 +++++++ doc/reference/cogl-pango/cogl-pango.toml.in | 44 +++++++++++++++++++++ doc/reference/cogl-pango/meson.build | 29 ++++++++++++++ doc/reference/cogl-pango/urlmap.js | 15 +++++++ doc/reference/cogl/cogl.toml.in | 44 +++++++++++++++++++++ doc/reference/cogl/meson.build | 25 ++++++++++++ doc/reference/cogl/urlmap.js | 15 +++++++ doc/reference/meson.build | 27 +++++++++++++ doc/reference/meta/meson.build | 34 ++++++++++++++++ doc/reference/meta/meta.toml.in | 44 +++++++++++++++++++++ doc/reference/meta/urlmap.js | 15 +++++++ meson.build | 10 +++++ meson_options.txt | 6 +++ 18 files changed, 485 insertions(+) create mode 100644 doc/reference/cally/cally.toml.in create mode 100644 doc/reference/cally/meson.build create mode 100644 doc/reference/cally/urlmap.js create mode 100644 doc/reference/clutter/clutter.toml.in create mode 100644 doc/reference/clutter/meson.build create mode 100644 doc/reference/clutter/urlmap.js create mode 100644 doc/reference/cogl-pango/cogl-pango.toml.in create mode 100644 doc/reference/cogl-pango/meson.build create mode 100644 doc/reference/cogl-pango/urlmap.js create mode 100644 doc/reference/cogl/cogl.toml.in create mode 100644 doc/reference/cogl/meson.build create mode 100644 doc/reference/cogl/urlmap.js create mode 100644 doc/reference/meson.build create mode 100644 doc/reference/meta/meson.build create mode 100644 doc/reference/meta/meta.toml.in create mode 100644 doc/reference/meta/urlmap.js diff --git a/doc/reference/cally/cally.toml.in b/doc/reference/cally/cally.toml.in new file mode 100644 index 000000000..385b8d5ee --- /dev/null +++ b/doc/reference/cally/cally.toml.in @@ -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" + diff --git a/doc/reference/cally/meson.build b/doc/reference/cally/meson.build new file mode 100644 index 000000000..62706e785 --- /dev/null +++ b/doc/reference/cally/meson.build @@ -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, +) diff --git a/doc/reference/cally/urlmap.js b/doc/reference/cally/urlmap.js new file mode 100644 index 000000000..afefc8296 --- /dev/null +++ b/doc/reference/cally/urlmap.js @@ -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/' ], +] diff --git a/doc/reference/clutter/clutter.toml.in b/doc/reference/clutter/clutter.toml.in new file mode 100644 index 000000000..e56b78570 --- /dev/null +++ b/doc/reference/clutter/clutter.toml.in @@ -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" + diff --git a/doc/reference/clutter/meson.build b/doc/reference/clutter/meson.build new file mode 100644 index 000000000..6b260c8e0 --- /dev/null +++ b/doc/reference/clutter/meson.build @@ -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, +) diff --git a/doc/reference/clutter/urlmap.js b/doc/reference/clutter/urlmap.js new file mode 100644 index 000000000..afefc8296 --- /dev/null +++ b/doc/reference/clutter/urlmap.js @@ -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/' ], +] diff --git a/doc/reference/cogl-pango/cogl-pango.toml.in b/doc/reference/cogl-pango/cogl-pango.toml.in new file mode 100644 index 000000000..95623816a --- /dev/null +++ b/doc/reference/cogl-pango/cogl-pango.toml.in @@ -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" + diff --git a/doc/reference/cogl-pango/meson.build b/doc/reference/cogl-pango/meson.build new file mode 100644 index 000000000..a5693489b --- /dev/null +++ b/doc/reference/cogl-pango/meson.build @@ -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, +) diff --git a/doc/reference/cogl-pango/urlmap.js b/doc/reference/cogl-pango/urlmap.js new file mode 100644 index 000000000..afefc8296 --- /dev/null +++ b/doc/reference/cogl-pango/urlmap.js @@ -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/' ], +] diff --git a/doc/reference/cogl/cogl.toml.in b/doc/reference/cogl/cogl.toml.in new file mode 100644 index 000000000..2eba52a91 --- /dev/null +++ b/doc/reference/cogl/cogl.toml.in @@ -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" + diff --git a/doc/reference/cogl/meson.build b/doc/reference/cogl/meson.build new file mode 100644 index 000000000..90b45cd42 --- /dev/null +++ b/doc/reference/cogl/meson.build @@ -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, +) diff --git a/doc/reference/cogl/urlmap.js b/doc/reference/cogl/urlmap.js new file mode 100644 index 000000000..afefc8296 --- /dev/null +++ b/doc/reference/cogl/urlmap.js @@ -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/' ], +] diff --git a/doc/reference/meson.build b/doc/reference/meson.build new file mode 100644 index 000000000..72665b511 --- /dev/null +++ b/doc/reference/meson.build @@ -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') diff --git a/doc/reference/meta/meson.build b/doc/reference/meta/meson.build new file mode 100644 index 000000000..f739b15ab --- /dev/null +++ b/doc/reference/meta/meson.build @@ -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, +) diff --git a/doc/reference/meta/meta.toml.in b/doc/reference/meta/meta.toml.in new file mode 100644 index 000000000..197ec600c --- /dev/null +++ b/doc/reference/meta/meta.toml.in @@ -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" + diff --git a/doc/reference/meta/urlmap.js b/doc/reference/meta/urlmap.js new file mode 100644 index 000000000..afefc8296 --- /dev/null +++ b/doc/reference/meta/urlmap.js @@ -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/' ], +] diff --git a/meson.build b/meson.build index fe57114ef..4334b8e6a 100644 --- a/meson.build +++ b/meson.build @@ -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') diff --git a/meson_options.txt b/meson_options.txt index 048a62b37..d84a3a44e 100644 --- a/meson_options.txt +++ b/meson_options.txt @@ -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,