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

[Jan Tojnar <jtojnar src gnome org>]

commit a106d1d9d8f43a373d06762a664d854f1af42c24
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       |  8 ++++++++
 docs/buoh.toml.in | 33 +++++++++++++++++++++++++++++++++
 docs/meson.build  | 33 +++++++++++++++++++++++++++++++++
 docs/urlmap.js    | 15 +++++++++++++++
 meson.build       | 14 ++++++++++++++
 meson_options.txt |  7 +++++++
 6 files changed, 110 insertions(+)
---
diff --git a/default.nix b/default.nix
index 8cbfa40..cf991a5 100644
--- a/default.nix
+++ b/default.nix
@@ -70,6 +70,7 @@ in (if shell then pkgs.mkShell else pkgs.stdenv.mkDerivation) rec {
     xvfb-run
     libxslt
     wrapGAppsHook
+    gi-docgen
   ] ++ lib.optionals shell [
     niv
   ];
@@ -91,6 +92,13 @@ in (if shell then pkgs.mkShell else pkgs.stdenv.mkDerivation) rec {
 
   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..f2e88a7
--- /dev/null
+++ b/docs/buoh.toml.in
@@ -0,0 +1,33 @@
+[library]
+version = "@VERSION@"
+description = "Comic strip viewer for GNOME"
+authors = [
+  "Esteban Sanchez",
+  "Pablo Arroyo",
+  "Carlos Garcia Campos",
+  "Pablo Castellano",
+]
+license = "GPL-2.0-or-later"
+website_url = "https://gitlab.gnome.org/GNOME/buoh/";
+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..2f4486d
--- /dev/null
+++ b/docs/meson.build
@@ -0,0 +1,33 @@
+if gi_docgen.found()
+  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 286ed8f..ffd098d 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())
@@ -24,6 +25,7 @@ schemadir = join_paths(datadir, 'glib-2.0', 'schemas')
 comicsdir = join_paths(pkgdatadir, 'comics')
 
 introspection_feature = get_option('introspection')
+api_docs_feature = get_option('api_docs')
 
 # Dependencies
 gtk = dependency('gtk+-3.0', version: '>= 3.22.0')
@@ -39,6 +41,17 @@ gtk_builder_tool = find_program('gtk-builder-tool', required: false)
 xmllint = find_program('xmllint', required: false)
 xsltproc = find_program('xsltproc', required: false)
 
+dependency(
+  'gi-docgen',
+  version: '>= 2021.1',
+  required: api_docs_feature,
+)
+gi_docgen = find_program('gi-docgen', required: api_docs_feature)
+
+if api_docs_feature.enabled() and introspection_feature.disabled()
+  error('Building “api_docs” requires the “introspection” feature to be enabled as well, make sure you have 
libgirepository installed.')
+endif
+
 buoh_deps = [
   gtk,
   glib,
@@ -67,3 +80,4 @@ gnome.post_install(
 subdir('src')
 subdir('data')
 subdir('po')
+subdir('docs')
diff --git a/meson_options.txt b/meson_options.txt
index 638b38f..39de944 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -4,3 +4,10 @@ option(
   value: 'auto',
   description: 'Generate introspection data for the executable (e.g. for static analysis)',
 )
+
+option(
+  'api_docs',
+  type: 'feature',
+  value: 'auto',
+  description: 'Use gi-docgen to build API documentation',
+)