[buoh/wip/jtojnar/gi-docgen: 2/2] Add code documentation
- From: Jan Tojnar <jtojnar src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [buoh/wip/jtojnar/gi-docgen: 2/2] Add code documentation
- Date: Wed, 4 May 2022 00:13:22 +0000 (UTC)
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',
+)
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]