[file-roller/wip/jtojnar/api_docs: 2/2] docs: Build API documentation using gi-docgen

[Jan Tojnar <jtojnar src gnome org>]

commit 81575ddc99586721b91a9ddccf7face12826ee42
Author: Jan Tojnar <jtojnar gmail com>
Date:   Mon May 16 01:18:24 2022 +0200

    docs: Build API documentation using gi-docgen
    
    This is not a library so it is not really useful for external consumers but it is still nice to have as a 
development reference.

 default.nix              |  7 +++++++
 docs/file-roller.toml.in | 26 ++++++++++++++++++++++++++
 docs/meson.build         | 33 +++++++++++++++++++++++++++++++++
 docs/urlmap.js           | 15 +++++++++++++++
 meson.build              | 13 +++++++++++++
 meson_options.txt        |  8 +++++++-
 6 files changed, 101 insertions(+), 1 deletion(-)
---
diff --git a/default.nix b/default.nix
index 340dff8a..655416a7 100644
--- a/default.nix
+++ b/default.nix
@@ -90,7 +90,9 @@ makeDerivation rec {
   nativeBuildInputs = with pkgs; [
     desktop-file-utils
     gettext
+    gi-docgen
     glibcLocales
+    gobject-introspection
     itstool
     libxml2
     meson
@@ -115,5 +117,10 @@ makeDerivation rec {
     libportal-gtk3
   ];
 
+  mesonFlags = [
+    "-Dintrospection=enabled"
+    "-Dapi_docs=enabled"
+  ];
+
   inherit doCheck;
 }
diff --git a/docs/file-roller.toml.in b/docs/file-roller.toml.in
new file mode 100644
index 00000000..19bc10e9
--- /dev/null
+++ b/docs/file-roller.toml.in
@@ -0,0 +1,26 @@
+[library]
+version = "@VERSION@"
+description = "An archive manager utility for GNOME"
+license = "GPL-2.0-or-later"
+browse_url = "https://gitlab.gnome.org/GNOME/file-roller/";
+repository_url = "https://gitlab.gnome.org/GNOME/file-roller.git";
+logo_url = "org.gnome.FileRoller.svg"
+devhelp = true
+search_index = true
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+# The base URL for the web UI
+base_url = "https://gitlab.gnome.org/GNOME/file-roller/-/blob/master/";
+# The format for links, using "filename" and "line" for the format
+file_format = "{filename}#L{line}"
+
+[extra]
+urlmap_file = "urlmap.js"
+content_images = [
+  "../data/icons/hicolor/scalable/apps/org.gnome.FileRoller.svg",
+]
diff --git a/docs/meson.build b/docs/meson.build
new file mode 100644
index 00000000..488338d9
--- /dev/null
+++ b/docs/meson.build
@@ -0,0 +1,33 @@
+if build_api_docs
+  toml_data = configuration_data()
+  toml_data.set('VERSION', meson.project_version())
+
+  fr_toml = configure_file(
+    input: 'file-roller.toml.in',
+    output: 'file-roller.toml',
+    configuration: toml_data,
+  )
+
+  custom_target(
+    'file-roller-doc',
+    input: [
+      fr_toml,
+      fr_gir[0],
+    ],
+    output: 'file-roller',
+    command: [
+      gi_docgen,
+      'generate',
+      '--quiet',
+      '--add-include-path=@0@'.format(meson.current_build_dir() / '../../src'),
+      '--config=@INPUT0@',
+      '--output-dir=@OUTPUT@',
+      '--no-namespace-dir',
+      '--content-dir=@0@'.format(meson.current_source_dir()),
+      '@INPUT1@',
+    ],
+    build_by_default: true,
+    install: true,
+    install_dir: docdir,
+  )
+endif
diff --git a/docs/urlmap.js b/docs/urlmap.js
new file mode 100644
index 00000000..2f4ada98
--- /dev/null
+++ b/docs/urlmap.js
@@ -0,0 +1,15 @@
+// SPDX-FileCopyrightText: 2021 GNOME Foundation
+// SPDX-License-Identifier: LGPL-2.1-or-later
+
+// Copied from GTK
+
+// A map between namespaces and base URLs for their online documentation
+baseURLs = [
+  ["GLib", "https://docs.gtk.org/glib/";],
+  ["Gio", "https://docs.gtk.org/gio/";],
+  ["GObject", "https://docs.gtk.org/gobject/";],
+  ["Gdk", "https://docs.gtk.org/gdk3/";],
+  ["GdkPixbuf", "https://docs.gtk.org/gdk-pixbuf/";],
+  ["Gtk", "https://docs.gtk.org/gtk3/";],
+  ["Pango", "https://docs.gtk.org/Pango/";]
+];
diff --git a/meson.build b/meson.build
index 89db09f4..6d63b6c3 100644
--- a/meson.build
+++ b/meson.build
@@ -17,6 +17,7 @@ gettext_package = meson.project_name()
 prefix = get_option('prefix')
 libdir = join_paths(prefix, get_option('libdir'))
 datadir = join_paths(prefix, get_option('datadir'))
+docdir = join_paths(datadir, 'doc')
 privexecdir = join_paths(prefix, get_option('libexecdir'), meson.project_name())
 c_comp = meson.get_compiler('c')
 
@@ -55,7 +56,18 @@ if get_option('cpio') == 'auto'
   endif
 endif
 
+gi_docgen = find_program(
+  'gi-docgen',
+  version: '>= 2021.1',
+  required: get_option('api_docs'),
+)
+
 build_introspection = gobject_introspection_dep.found()
+build_api_docs = gi_docgen.found()
+
+if build_api_docs and not build_introspection
+  error('Building “api_docs” requires the “introspection” feature to be enabled as well, make sure you have 
libgirepository installed.')
+endif
 
 # config.h
 
@@ -131,6 +143,7 @@ if build_nautilus_actions
 endif
 subdir('po')
 subdir('src')
+subdir('docs')
 
 gnome.post_install(
   gtk_update_icon_cache: true,
diff --git a/meson_options.txt b/meson_options.txt
index 8b5746a9..ca5aff63 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -45,5 +45,11 @@ option('cpio',
 option('introspection',
   type : 'feature',
   value : 'disabled',
-  description : 'Generate introspection data for the executable (e.g. for static analysis)'
+  description : 'Generate introspection data for the executable (e.g. for static analysis and API docs)'
+)
+
+option('api_docs',
+  type : 'feature',
+  value : 'disabled',
+  description : 'Use gi-docgen to build API documentation (only useful for people developing File Roller)'
 )