GNOME.org
 

[libshumate] docs: Switch to gi-docgen

commit 02aaa3411168534a3d274be114843037aca02a72
Author: James Westman <james flyingpimonster net>
Date:   Mon May 17 19:42:08 2021 -0500

    docs: Switch to gi-docgen
    
    - Don't build docs in flatpak. It would require a bunch of extra modules
      for gi-docgen's dependencies, and doc generation can take a little
      while anyway. Better to leave it out.
    - Remove the gtk-doc files and add gi-docgen to the build system.

 .gitignore                             |   1 +
 .gitlab-ci.yml                         |   5 +-
 demos/org.gnome.Shumate.Demo.json      |   3 +-
 docs/libshumate.toml.in                |  43 +++
 docs/meson.build                       |  37 ++-
 docs/reference/libshumate-docs.sgml    | 101 ------
 docs/reference/libshumate-sections.txt | 566 ---------------------------------
 docs/reference/libshumate.types        |  19 --
 docs/reference/meson.build             |  65 ----
 docs/reference/version.xml.in          |   1 -
 docs/urlmap.js                         |  16 +
 meson.build                            |  19 +-
 meson_options.txt                      |   4 +-
 subprojects/gi-docgen.wrap             |   7 +
 14 files changed, 119 insertions(+), 768 deletions(-)
---
diff --git a/.gitignore b/.gitignore
index 7b304b2..c9da453 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,3 +3,4 @@
 *.sw?
 *.pyc
 build
+/subprojects/gi-docgen
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index c3c8d1a..1bcf555 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -8,10 +8,9 @@ fedora:
   script:
     - sudo dnf install -y vala sqlite-devel libsoup-devel gtk4-devel
     - meson _build -Db_coverage=true -Dgtk_doc=true
-    - ninja -C _build shumate-doc
     - xvfb-run ninja -C _build test
     - ninja -C _build coverage
-    - mv _build/docs/reference/html/ docs
+    - mv _build/docs/libshumate-0.0 docs
     - mv _build/meson-logs/coveragereport coverage
   coverage: '/^\s+lines\.+:\s+([\d.]+\%)\s+/'
   artifacts:
@@ -24,7 +23,7 @@ pages:
   dependencies:
   - fedora
   script:
-  - mv docs/html public
+  - mv docs/libshumate-0.0 public
   - mv coverage public/
   artifacts:
     paths:
diff --git a/demos/org.gnome.Shumate.Demo.json b/demos/org.gnome.Shumate.Demo.json
index 06932aa..f43c207 100644
--- a/demos/org.gnome.Shumate.Demo.json
+++ b/demos/org.gnome.Shumate.Demo.json
@@ -32,8 +32,7 @@
             "name" : "libshumate",
             "buildsystem" : "meson",
             "config-opts" : [
-                "-Ddemos=true",
-                "-Dgtk_doc=true"
+                "-Ddemos=true"
             ],
             "builddir" : true,
             "sources" : [
diff --git a/docs/libshumate.toml.in b/docs/libshumate.toml.in
new file mode 100644
index 0000000..5f35807
--- /dev/null
+++ b/docs/libshumate.toml.in
@@ -0,0 +1,43 @@
+[library]
+version = "@VERSION@"
+description = "GTK4 widget to display maps"
+authors = "libshumate contributors"
+license = "LGPL-2.1-or-later"
+browse_url = "https://gitlab.gnome.org/GNOME/libshumate/";
+repository_url = "https://gitlab.gnome.org/GNOME/libshumate.git";
+website_url = "https://gnome.pages.gitlab.gnome.org/libshumate";
+dependencies = [
+  "GObject-2.0",
+  "Gtk-4.0",
+]
+devhelp = true
+search_index = true
+
+[dependencies."GObject-2.0"]
+name = "GObject"
+description = "The base type system library"
+docs_url = "https://developer.gnome.org/gobject/stable";
+
+[dependencies."Gtk-4.0"]
+name = "GTK"
+description = "The GTK toolkit"
+docs_url = "https://docs.gtk.org/gtk4/";
+
+[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/libshumate/-/blob/main/";
+# The format for links, using "filename" and "line" for the format
+file_format = "{filename}#L{line}"
+
+[extra]
+urlmap_file = "urlmap.js"
+content_files = [
+]
+content_images = [
+]
+
diff --git a/docs/meson.build b/docs/meson.build
index db1d8de..b2611ac 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -1,3 +1,34 @@
-if build_gtk_doc == true
-  subdir('reference')
-endif
\ No newline at end of file
+if get_option('gtk_doc')
+
+expand_content_md_files = [
+]
+
+libshumate_doc_toml = configure_file(
+  input: 'libshumate.toml.in',
+  output: 'libshumate.toml',
+  configuration: {
+    'VERSION': meson.project_version(),
+  }
+)
+
+custom_target('libshumate-doc',
+  input: [ libshumate_doc_toml, libshumate_gir[0] ],
+  output: 'libshumate-@0@'.format(lib_version),
+  command: [
+    gidocgen,
+    'generate',
+    '--quiet',
+    '--add-include-path=@0@'.format(meson.current_build_dir() / '../shumate'),
+    '--config=@INPUT0@',
+    '--output-dir=@OUTPUT@',
+    '--no-namespace-dir',
+    '--content-dir=@0@'.format(meson.current_source_dir()),
+    '@INPUT1@',
+  ],
+  depend_files: [ expand_content_md_files ],
+  build_by_default: true,
+  install: true,
+  install_dir: docs_dir,
+)
+
+endif
diff --git a/docs/urlmap.js b/docs/urlmap.js
new file mode 100644
index 0000000..581f66c
--- /dev/null
+++ b/docs/urlmap.js
@@ -0,0 +1,16 @@
+// 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 = [
+    [ 'Gdk', 'https://docs.gtk.org/gdk4/' ],
+    [ 'GdkWayland', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4-wayland/' ],
+    [ 'GdkX11', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4-x11/' ],
+    [ 'Gsk', 'https://docs.gtk.org/gsk4/' ],
+    [ 'Gtk', 'https://docs.gtk.org/gtk4/' ],
+    [ 'Pango', 'https://docs.gtk.org/Pango/' ],
+    [ 'PangoCairo', 'https://gnome.pages.gitlab.gnome.org/pango/pangocairo/' ],
+]
+
diff --git a/meson.build b/meson.build
index 6564a49..0ad4b99 100644
--- a/meson.build
+++ b/meson.build
@@ -2,7 +2,7 @@ project(
   'libshumate', 'c',
   version: '0.0.0',
   license: 'LGPLv2.1+',
-  meson_version: '>= 0.46.1',
+  meson_version: '>= 0.53.0',
   default_options: [
     'buildtype=debugoptimized',
   ]
@@ -45,7 +45,7 @@ typelibdir = join_paths(libdir, 'girepository-1.0')
 pkgconfigdir = join_paths(libdir, 'pkgconfig')
 
 girdir = join_paths(datadir, 'gir-1.0')
-gtkdocdir = join_paths(datadir, 'gtk-doc')
+docs_dir = datadir / 'docs'
 vapidir = join_paths(datadir, 'vala', 'vapi')
 
 # Dependencies
@@ -73,6 +73,14 @@ introspection_dep = dependency('gobject-introspection-1.0', version: introspecti
 vapigen_dep = dependency('vapigen', version: vala_req, required: false)
 gtk_doc_dep = dependency('gtk-doc', version: gtk_doc_req, required: false)
 
+if get_option('gtk_doc')
+  dependency('gi-docgen',
+    version: '>= 2021.1',
+    fallback: ['gi-docgen', 'dummy_dep'],
+  )
+  gidocgen = find_program('gi-docgen')
+endif
+
 # Configurations
 config_h = configuration_data()
 config_h.set_quoted('VERSION', version)
@@ -85,9 +93,8 @@ configure_file(
 # Options
 build_demos = get_option('demos')
 
-build_gtk_doc = get_option('gtk_doc')
-if build_gtk_doc and not gtk_doc_dep.found()
-  build_gtk_doc = false
+if get_option('gtk_doc') and not get_option('gir')
+  error('Cannot generate the documentation if gobjet-introspection is disabled.')
 endif
 
 generate_gir = get_option('gir')
@@ -118,7 +125,7 @@ summary = [
   'libshumate @0@ (@1@)'.format(version, api_version),
   '',
   '             Demos: @0@'.format(build_demos),
-  '     Documentation: @0@'.format(build_gtk_doc),
+  '     Documentation: @0@'.format(get_option('gtk_doc')),
   '     Introspection: @0@'.format(generate_gir),
   '          Vala API: @0@'.format(generate_vapi),
   '',
diff --git a/meson_options.txt b/meson_options.txt
index 0ca9148..ad9ae50 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -7,8 +7,8 @@ option('vapi',
 
 option('gtk_doc',
        type: 'boolean', value: false,
-       description: 'Build reference manual (requires gtk-doc)')
+       description: 'Build reference manual (requires gi-docgen installed and gir enabled)')
 
 option('demos',
        type: 'boolean', value: false,
-       description: 'Build demonstration programs')
\ No newline at end of file
+       description: 'Build demonstration programs')
diff --git a/subprojects/gi-docgen.wrap b/subprojects/gi-docgen.wrap
new file mode 100644
index 0000000..fb001c2
--- /dev/null
+++ b/subprojects/gi-docgen.wrap
@@ -0,0 +1,7 @@
+[wrap-git]
+directory=gi-docgen
+url=https://gitlab.gnome.org/GNOME/gi-docgen.git
+push-url=ssh://git gitlab gnome org:GNOME/gi-docgen.git
+revision=main
+depth=1
+
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]