GNOME.org
 

[libpeas] gi-docgen: Initial commit

commit 82119a6b60899362d3847802e0927fc225e9a95e
Author: Maximiliano Sandoval R <msandova gnome org>
Date:   Sun Mar 13 11:44:25 2022 +0100

    gi-docgen: Initial commit

 .gitlab-ci.yml                       |  45 ++++---
 README                               |   8 ++
 docs/meson.build                     |   4 +-
 docs/reference/.gitignore            |  15 ---
 docs/reference/libpeas-docs.sgml     |  68 -----------
 docs/reference/libpeas-gtk-urlmap.js |   8 ++
 docs/reference/libpeas-gtk.toml.in   |  55 +++++++++
 docs/reference/libpeas-overrides.txt |   0
 docs/reference/libpeas-sections.txt  | 229 -----------------------------------
 docs/reference/libpeas-urlmap.js     |   7 ++
 docs/reference/libpeas.toml.in       |  44 +++++++
 docs/reference/libpeas.types         |  10 --
 docs/reference/meson.build           | 145 +++++++++-------------
 docs/reference/version.xml.in        |   1 -
 meson.build                          |  16 +--
 meson_options.txt                    |   2 +-
 subprojects/gi-docgen.wrap           |   6 +
 17 files changed, 222 insertions(+), 441 deletions(-)
---
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 9170801d..9fa231fb 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -3,7 +3,7 @@ stages:
   - 'deploy'
 
 .build:
-  image: 'registry.fedoraproject.org/fedora:30'
+  image: 'registry.fedoraproject.org/fedora:35'
   stage: 'build'
   variables:
     CCACHE_BASEDIR: "${CI_PROJECT_DIR}"
@@ -12,7 +12,6 @@ stages:
       gcc
       ccache
       gettext
-      gtk-doc
       meson
       ninja-build
       redhat-rpm-config
@@ -22,11 +21,14 @@ stages:
       python2-devel
       python3-devel
       xorg-x11-server-Xvfb
+      git
+      pip
   before_script:
     - "dnf install -y $DEPS"
     - 'mkdir -p _ccache'
     - 'ccache --zero-stats'
     - 'ccache --show-stats'
+    - 'pip install markdown markupsafe pygments jinja2 toml typogrify'
   after_script:
     - 'ccache --show-stats'
   cache:
@@ -37,31 +39,40 @@ stages:
 build peas:
   extends: '.build'
   script:
-    - 'meson -Dwidgetry=false -Dintrospection=true -Dvapi=true -Ddemos=false _build .'
+    - 'meson -Dwidgetry=false -Dintrospection=true -Dvapi=true -Ddemos=false -Dgtk_doc=false _build .'
     - 'ninja -C _build test'
 
 build peas-gtk:
   extends: '.build'
   script:
-    - 'meson -Dwidgetry=true -Dglade_catalog=true -Dintrospection=true -Dvapi=true -Dgtk_doc=true _build .'
+    - 'meson -Dwidgetry=true -Dglade_catalog=true -Dintrospection=true -Dvapi=true -Dgtk_doc=false _build .'
     - 'xvfb-run -a -s "-screen 0 1024x768x24"  ninja -C _build test'
-    - 'ninja -C _build libpeas-doc'
+
+reference:
+  extends: '.build'
+  variables:
+    MESON_ARGS: >-
+      -Dgtk_doc=true
+      -Ddemos=false
+      -Dglade_catalog=false
+      -Dwidgetry=true
+  script:
+    - mkdir -p _reference/libpeas-1.0
+    - mkdir -p _reference/libpeas-gtk-1.0
+    - meson ${MESON_ARGS} _build
+    - ninja -C _build
+    - mv _build/docs/reference/libpeas-1.0/* _reference/libpeas-1.0
+    - mv _build/docs/reference/libpeas-gtk-1.0/* _reference/libpeas-gtk-1.0
   artifacts:
-    name: 'libpeas-doc'
     paths:
-      - '_build/docs/reference/html'
+      - _reference
 
 pages:
-  image: 'registry.fedoraproject.org/fedora:30'
-  stage: 'deploy'
-  dependencies:
-    - 'build peas'
-    - 'build peas-gtk'
+  stage: deploy
+  needs: ['reference']
   script:
-    - 'mkdir -p public/'
-    - 'mv _build/docs/reference/html/ public/libpeas/'
+    - mv _reference public
   artifacts:
+    when: on_success
     paths:
-      - 'public'
-  only:
-    - 'master'
+      - public
diff --git a/README b/README
index 3183089f..857c100a 100644
--- a/README
+++ b/README
@@ -9,6 +9,14 @@ It takes its roots in the old gedit plugins engine, and provides an extensive se
 of features mirroring the desiderata of most of the applications providing an
 extension framework.
 
+Documentation
+-------------------------
+
+Documentation can be found at:
+
+- Peas-1.0: https://gnome.pages.gitlab.gnome.org/libpeas/libpeas-1.0/.
+- GtkPeas-1.0: https://gnome.pages.gitlab.gnome.org/libpeas/libpeas-gtk-1.0/.
+
 Multiple extension points
 -------------------------
 
diff --git a/docs/meson.build b/docs/meson.build
index c662ff07..ead14c40 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -1,3 +1 @@
-if build_gtk_doc == true
-  subdir('reference')
-endif
+subdir('reference')
diff --git a/docs/reference/libpeas-gtk-urlmap.js b/docs/reference/libpeas-gtk-urlmap.js
new file mode 100644
index 00000000..0b6777e6
--- /dev/null
+++ b/docs/reference/libpeas-gtk-urlmap.js
@@ -0,0 +1,8 @@
+// A map between namespaces and base URLs for their online documentation
+baseURLs = [
+    [ 'GLib', 'https://docs.gtk.org/glib/' ],
+    [ 'GObject', 'https://docs.gtk.org/gobject/' ],
+    [ 'Gio', 'https://docs.gtk.org/gio/' ],
+    [ 'Gtk', 'https://docs.gtk.org/gtk4/' ],
+    [ 'Peas', 'https://gnome.pages.gitlab.gnome.org/libpeas/libpeas-1.0/' ],
+]
diff --git a/docs/reference/libpeas-gtk.toml.in b/docs/reference/libpeas-gtk.toml.in
new file mode 100644
index 00000000..4994389c
--- /dev/null
+++ b/docs/reference/libpeas-gtk.toml.in
@@ -0,0 +1,55 @@
+[library]
+version = "@VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/libpeas";
+repository_url = "https://gitlab.gnome.org/GNOME/libpeas.git";
+docs_url = "https://gnome.pages.gitlab.gnome.org/libpeas/libpeas-gtk-1.0/";
+website_url = "https://gitlab.gnome.org/GNOME/libpeas";
+authors = "Steve Frécinaux, Garrett Regier, Christian Hergert"
+license = "LGPL-2.0-or-later"
+description = "HTTP client/server library for GNOME"
+dependencies = [ "GObject-2.0", "GLib-1.0", "Gio-2.0", "Gtk-3.0", "Peas-1.0" ]
+devhelp = true
+search_index = true
+
+[dependencies."GObject-2.0"]
+name = "GObject"
+description = "The base type system library"
+docs_url = "https://docs.gtk.org/gobject/";
+
+[dependencies."GLib-2.0"]
+name = "GLib"
+description = "The base type system library"
+docs_url = "https://docs.gtk.org/glib/";
+
+[dependencies."Gio-2.0"]
+name = "GIO"
+description = "GObject Interfaces and Objects, Networking, IPC, and I/O"
+docs_url = "https://docs.gtk.org/gio/";
+
+[dependencies."Gtk-3.0"]
+name = "GTK"
+description = "The GTK toolkit"
+docs_url = "https://docs.gtk.org/gtk3/";
+
+[dependencies."Peas-1.0"]
+name = "Peas"
+description = "GObject-based plugins engine"
+docs_url = "https://gnome.pages.gitlab.gnome.org/libpeas/libpeas-1.0/";
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/libpeas/-/blob/master/";
+
+[extra]
+# The same order will be used when generating the index
+content_files = [
+]
+
+content_images = [
+  'images/peas-gtk-plugin-manager.png',
+]
+urlmap_file = "libpeas-gtk-urlmap.js"
diff --git a/docs/reference/libpeas-urlmap.js b/docs/reference/libpeas-urlmap.js
new file mode 100644
index 00000000..a0ce5e68
--- /dev/null
+++ b/docs/reference/libpeas-urlmap.js
@@ -0,0 +1,7 @@
+// A map between namespaces and base URLs for their online documentation
+baseURLs = [
+    [ 'GLib', 'https://docs.gtk.org/glib/' ],
+    [ 'GObject', 'https://docs.gtk.org/gobject/' ],
+    [ 'Gio', 'https://docs.gtk.org/gio/' ],
+    [ 'Gtk', 'https://docs.gtk.org/gtk4/' ],
+]
diff --git a/docs/reference/libpeas.toml.in b/docs/reference/libpeas.toml.in
new file mode 100644
index 00000000..05e47ab0
--- /dev/null
+++ b/docs/reference/libpeas.toml.in
@@ -0,0 +1,44 @@
+[library]
+version = "@VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/libpeas";
+repository_url = "https://gitlab.gnome.org/GNOME/libpeas.git";
+docs_url = "https://gnome.pages.gitlab.gnome.org/libpeas/libpeas-1.0/";
+website_url = "https://gitlab.gnome.org/GNOME/libpeas";
+authors = "Steve Frécinaux, Garrett Regier, Christian Hergert"
+license = "LGPL-2.0-or-later"
+description = "HTTP client/server library for GNOME"
+dependencies = [ "GObject-2.0", "GLib-1.0", "Gio-2.0" ]
+devhelp = true
+search_index = true
+
+[dependencies."GObject-2.0"]
+name = "GObject"
+description = "The base type system library"
+docs_url = "https://docs.gtk.org/gobject/";
+
+[dependencies."GLib-2.0"]
+name = "GLib"
+description = "The base type system library"
+docs_url = "https://docs.gtk.org/glib/";
+
+[dependencies."Gio-2.0"]
+name = "GIO"
+description = "GObject Interfaces and Objects, Networking, IPC, and I/O"
+docs_url = "https://docs.gtk.org/gio/";
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/libpeas/-/blob/master/";
+
+[extra]
+# The same order will be used when generating the index
+content_files = [
+]
+
+content_images = [
+]
+urlmap_file = "libpeas-urlmap.js"
diff --git a/docs/reference/meson.build b/docs/reference/meson.build
index bac8849a..fd4b5138 100644
--- a/docs/reference/meson.build
+++ b/docs/reference/meson.build
@@ -1,99 +1,64 @@
-glib_prefix = glib_dep.get_pkgconfig_variable('prefix')
-glib_docpath = join_paths(glib_prefix, 'share', 'gtk-doc', 'html')
-
-gtk_prefix = gtk_dep.get_pkgconfig_variable('prefix')
-gtk_docpath = join_paths(gtk_prefix, 'share', 'gtk-doc', 'html')
-
-libpeas_reference_ignored_h = [
-  'gconstructor.h',
-  'peas-debug.h',
-  'peas-dirs.h',
-  'peas-engine-priv.h',
-  'peas-introspection.h',
-  'peas-marshal.h',
-  'peas-plugin-info-priv.h',
-  'peas-plugin-loader.h',
-  'peas-plugin-loader-c.h',
-  'peas-utils.h',
-]
-
-libpeas_reference_html_images = [
+expand_content_md_files = [
 ]
 
-libpeas_reference_srcdirs = [
-  libpeas_srcdir,
-]
-
-if build_gtk_widgetry == true
-  libpeas_reference_ignored_h += [
-    'peas-gtk-disable-plugins-dialog.h',
-    'peas-gtk-plugin-manager-store.h',
-  ]
+toml_data = configuration_data()
+toml_data.set('VERSION', meson.project_version())
 
-  libpeas_reference_html_images += [
-    join_paths('images', 'peas-gtk-plugin-manager.png'),
-  ]
-
-  libpeas_reference_srcdirs += [
-    libpeas_gtk_srcdir,
-  ]
-endif
-
-version_xml = configuration_data()
-version_xml.set('PEAS_VERSION', version)
-
-configure_file(
-  input: 'version.xml.in',
-  output: 'version.xml',
-  configuration: version_xml,
+libpeas_toml = configure_file(
+  input: 'libpeas.toml.in',
+  output: 'libpeas.toml',
+  configuration: toml_data
 )
 
-libpeas_reference_deps = [
-  libpeas_dep,
-]
-
-libpeas_reference_scan_args = [
-  '--rebuild-types',
-  '--deprecated-guards="PEAS_DISABLE_DEPRECATED"',
-  '--ignore-headers=' + ' '.join(libpeas_reference_ignored_h),
-]
-
-libpeas_reference_fixxref_args = [
-  '--extra-dir=@0@'.format(join_paths(glib_docpath, 'glib')),
-  '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gobject')),
-  '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gmodule')),
-  '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gio')),
-]
-
-libpeas_reference_mkdb_args = [
-  '--sgml-mode',
-  '--output-format=xml',
-]
+gidocgen = find_program('gi-docgen')
+
+docs_dir = get_option('datadir') / 'doc'
+
+custom_target('libpeas-doc',
+  input: [libpeas_toml, libpeas_gir[0]],
+  output: 'libpeas-@0@'.format(api_version),
+  command: [
+    gidocgen,
+    'generate',
+    '--quiet',
+    '--add-include-path=@0@'.format(meson.current_build_dir() / '../../libpeas'),
+    '--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,
+)
 
 if build_gtk_widgetry == true
-  libpeas_reference_deps += [
-    libpeas_gtk_dep,
-  ]
-
-  libpeas_reference_fixxref_args += [
-    '--extra-dir=@0@'.format(join_paths(gtk_docpath, 'gtk')),
-  ]
-endif
+  libpeas_gtk_toml = configure_file(
+    input: 'libpeas-gtk.toml.in',
+    output: 'libpeas-gtk.toml',
+    configuration: toml_data
+  )
 
-gnome.gtkdoc(
-  package_name,
-  main_sgml: 'libpeas-docs.sgml',
-  gobject_typesfile: 'libpeas.types',
-  src_dir: libpeas_reference_srcdirs,
-  html_assets: libpeas_reference_html_images,
-  dependencies: libpeas_reference_deps,
-  scan_args: libpeas_reference_scan_args,
-  fixxref_args: libpeas_reference_fixxref_args,
-  mkdb_args: libpeas_reference_mkdb_args,
-  install: true,
-  install_dir: join_paths(
-    gtkdocdir,
-    'html',
-    package_name,
+  custom_target('libpeas-gtk-doc',
+    input: [libpeas_gtk_toml, libpeas_gtk_gir[0], libpeas_gir[0]],
+    output: 'libpeas-gtk-@0@'.format(api_version),
+    command: [
+      gidocgen,
+      'generate',
+      '--quiet',
+      '--add-include-path=@0@'.format(meson.current_build_dir() / '../../libpeas-gtk'),
+      '--add-include-path=@0@'.format(meson.current_build_dir() / '../../libpeas'),
+      '--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/meson.build b/meson.build
index ba250ea4..72325635 100644
--- a/meson.build
+++ b/meson.build
@@ -66,7 +66,6 @@ pkglibdir = join_paths(libdir, package_string)
 pkgdatadir = join_paths(datadir, package_string)
 
 girdir = join_paths(datadir, 'gir-1.0')
-gtkdocdir = join_paths(datadir, 'gtk-doc')
 iconsdir = join_paths(datadir, 'icons')
 pkgconfigdir = join_paths(libdir, 'pkgconfig')
 typelibdir = join_paths(libdir, 'girepository-1.0')
@@ -107,7 +106,10 @@ gio_dep = dependency('gio-2.0', version: glib_req)
 introspection_dep = dependency('gobject-introspection-1.0', version: introspection_req)
 gtk_dep = dependency('gtk+-3.0', version: gtk_req, required: false)
 
-gtk_doc_dep = dependency('gtk-doc', version: gtk_doc_req, required: false)
+gi_docgen_dep = dependency('gi-docgen', version: '>= 2021.7',
+                           fallback: ['gi-docgen', 'dummy_dep'],
+                           native: true,
+                           required: get_option('gtk_doc'))
 gladeui_dep = dependency('gladeui-2.0', required: false)
 
 # From python 3.8 we neeed python3-embed
@@ -249,10 +251,7 @@ configure_file(
 )
 
 # Options
-build_gtk_doc = get_option('gtk_doc')
-if build_gtk_doc and not gtk_doc_dep.found()
-  build_gtk_doc = false
-endif
+build_gtk_doc = gi_docgen_dep.found()
 
 install_glade_catalog = get_option('glade_catalog')
 if install_glade_catalog and not gladeui_dep.found()
@@ -310,7 +309,10 @@ if build_gtk_widgetry == true
   subdir('libpeas-gtk')
 endif
 
-subdir('docs')
+if build_gtk_doc == true
+  subdir('docs')
+endif
+
 subdir('data')
 subdir('po')
 
diff --git a/meson_options.txt b/meson_options.txt
index 9c4a4bf5..cb21e45a 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -36,4 +36,4 @@ option('demos',
 
 option('gtk_doc',
        type: 'boolean', value: false,
-       description: 'Build reference manual (requires gtk-doc)')
+       description: 'Build reference manual (requires gi-docgen)')
diff --git a/subprojects/gi-docgen.wrap b/subprojects/gi-docgen.wrap
new file mode 100644
index 00000000..98cd9211
--- /dev/null
+++ b/subprojects/gi-docgen.wrap
@@ -0,0 +1,6 @@
+[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]