[buoh/wip/jtojnar/gi-docgen: 2/2] Add code documentation

[Jan Tojnar <jtojnar src gnome org>]

commit 15f61da9c6531b44e926c31e8a74175045ac0cdb
Author: Jan Tojnar <jtojnar gmail com>
Date:   Wed May 4 01:27:34 2022 +0200

    Add code documentation
    
    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       |  9 +++++++++
 docs/buoh.toml.in | 26 ++++++++++++++++++++++++++
 docs/meson.build  | 33 +++++++++++++++++++++++++++++++++
 docs/urlmap.js    | 15 +++++++++++++++
 meson.build       | 13 +++++++++++++
 meson_options.txt |  7 +++++++
 6 files changed, 103 insertions(+)
---
diff --git a/default.nix b/default.nix
index 429a732..532f3f0 100644
--- a/default.nix
+++ b/default.nix
@@ -66,6 +66,7 @@ in (if shell then pkgs.mkShell else pkgs.stdenv.mkDerivation) rec {
     ninja
     pkg-config
     gettext
+    gi-docgen
     gobject-introspection
     python3
     xvfb-run
@@ -92,10 +93,18 @@ in (if shell then pkgs.mkShell else pkgs.stdenv.mkDerivation) rec {
 
   mesonFlags = [
     "-Dintrospection=enabled"
+    "-Dapi_docs=enabled"
   ];
 
   inherit doCheck;
 
+  preBuild = ''
+    # Generating introspection needed for building docs runs BuohApplication,
+    # which tries to create config file in XDG_CONFIG_DIR,
+    # so we need to point HOME to an existing directory.
+    export HOME="$TMPDIR"
+  '';
+
   # Hardening does not work in debug mode
   hardeningDisable = lib.optionals shell [ "all" ];
 
diff --git a/docs/buoh.toml.in b/docs/buoh.toml.in
new file mode 100644
index 0000000..ad6bbc9
--- /dev/null
+++ b/docs/buoh.toml.in
@@ -0,0 +1,26 @@
+[library]
+version = "@VERSION@"
+description = "Comic strip viewer for GNOME"
+license = "GPL-2.0-or-later"
+browse_url = "https://gitlab.gnome.org/GNOME/buoh/";
+repository_url = "https://gitlab.gnome.org/GNOME/buoh.git";
+logo_url = "buoh.png"
+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/buoh/-/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/64x64/buoh.png",
+]
diff --git a/docs/meson.build b/docs/meson.build
new file mode 100644
index 0000000..439831a
--- /dev/null
+++ b/docs/meson.build
@@ -0,0 +1,33 @@
+if api_docs_enabled
+  toml_data = configuration_data()
+  toml_data.set('VERSION', meson.project_version())
+
+  buoh_toml = configure_file(
+    input: 'buoh.toml.in',
+    output: 'buoh.toml',
+    configuration: toml_data,
+  )
+
+  custom_target(
+    'buoh-doc',
+    input: [
+      buoh_toml,
+      buoh_gir[0],
+    ],
+    output: 'buoh',
+    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 0000000..2f4ada9
--- /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 dc74faa..d7f814d 100644
--- a/meson.build
+++ b/meson.build
@@ -17,6 +17,7 @@ po_dir = join_paths(meson.current_source_dir(), 'po')
 prefix = get_option('prefix')
 bindir = join_paths(prefix, get_option('bindir'))
 datadir = join_paths(prefix, get_option('datadir'))
+docdir = join_paths(datadir, 'doc')
 icondir = join_paths(datadir, 'icons', 'hicolor')
 localedir = join_paths(prefix, get_option('localedir'))
 pkgdatadir = join_paths(datadir, meson.project_name())
@@ -37,7 +38,18 @@ gtk_builder_tool = find_program('gtk-builder-tool', required: false)
 xmllint = find_program('xmllint', required: false)
 xsltproc = find_program('xsltproc', required: false)
 
+gi_docgen = find_program(
+  'gi-docgen',
+  version: '>= 2021.1',
+  required: get_option('api_docs'),
+)
+
 introspection_enabled = gobject_introspection.found()
+api_docs_enabled = gi_docgen.found()
+
+if api_docs_enabled and not introspection_enabled
+  error('Building “api_docs” requires the “introspection” feature to be enabled as well, make sure you have 
libgirepository installed.')
+endif
 
 buoh_deps = [
   gtk,
@@ -67,3 +79,4 @@ gnome.post_install(
 subdir('src')
 subdir('data')
 subdir('po')
+subdir('docs')
diff --git a/meson_options.txt b/meson_options.txt
index 0df308a..f4799ac 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -4,3 +4,10 @@ option(
   value: 'disabled',
   description: 'Generate introspection data for the executable (e.g. for static analysis)',
 )
+
+option(
+  'api_docs',
+  type: 'feature',
+  value: 'disabled',
+  description: 'Use gi-docgen to build API documentation',
+)