[librest/gwagner/docs] Add gi-docgen and proper documentation CI

[Günther Wagner <gwagner src gnome org>]

commit 2196640391fc890decf2aae3eeabf6befbd24476
Author: Günther Wagner <info gunibert de>
Date:   Thu Oct 21 19:36:05 2021 +0200

    Add gi-docgen and proper documentation CI

 .gitlab-ci.yml             | 57 +++++++++++++++++++++++++++++++++++-
 docs/librest.toml.in       | 72 ++++++++++++++++++++++++++++++++++++++++++++++
 docs/meson.build           | 42 +++++++++++++++++++++++++++
 meson.build                |  3 ++
 subprojects/gi-docgen.wrap |  6 ++++
 5 files changed, 179 insertions(+), 1 deletion(-)
---
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 53873dd..aee94b5 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -1,7 +1,9 @@
-image: fedora:latest
+image: fedora:34
 
 stages:
   - build
+  - docs
+  - deploy
 
 build-librest:
   stage: build
@@ -25,3 +27,56 @@ build-librest:
       - "_build/config.h"
       - "_build/meson-logs"
       - "_build/${CI_JOB_NAME}-report.xml"
+
+.gidocgen-build:
+  image: fedora:latest
+  before_script:
+    - export PATH="$HOME/.local/bin:$PATH"
+    - dnf install -y python3 python3-pip python3-wheel gobject-introspection-devel graphviz ninja-build 
redhat-rpm-config
+    - dnf install -y ${PROJECT_DEPS}
+    - pip3 install --user meson==${MESON_VERSION} gi-docgen jinja2 Markdown markupsafe pygments toml 
typogrify
+  script:
+    - meson setup ${MESON_EXTRA_FLAGS} ${DOCS_FLAGS} _docs .
+    - meson compile -C _docs
+    - |
+      pushd "_docs/${DOCS_PATH}" > /dev/null
+      tar cf ${CI_PROJECT_NAME}-docs.tar .
+      popd > /dev/null
+    - mv _docs/${DOCS_PATH}/${CI_PROJECT_NAME}-docs.tar .
+  artifacts:
+    when: always
+    name: 'Documentation'
+    expose_as: 'Download the API reference'
+    paths:
+      - ${CI_PROJECT_NAME}-docs.tar
+
+reference:
+  stage: docs
+  needs: []
+  extends: .gidocgen-build
+  variables:
+    PROJECT_DEPS:
+      docbook-style-xsl
+      gcc
+      gettext
+      git
+      glib2-devel
+      libxslt
+      libsoup-devel
+      gtk-doc
+    MESON_VERSION: "0.55.3"
+    MESON_EXTRA_FLAGS: "-Dintrospection=true"
+    DOCS_FLAGS: -Dgtk_doc=true
+    DOCS_PATH: doc/librest-1.0
+
+pages:
+  stage: deploy
+  needs: ['reference']
+  script:
+    - mkdir public && cd public
+    - tar xf ../${CI_PROJECT_NAME}-docs.tar
+  artifacts:
+    paths:
+      - public
+  only:
+    - master
diff --git a/docs/librest.toml.in b/docs/librest.toml.in
new file mode 100644
index 0000000..6db13e8
--- /dev/null
+++ b/docs/librest.toml.in
@@ -0,0 +1,72 @@
+[library]
+namespace = "Rest"
+version = "@REST_VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/librest/";
+repository_url = "https://gitlab.gnome.org/GNOME/librest.git";
+authors = "Günther Wagner"
+license = "LGPL-2.1-or-later"
+description = "REST client library"
+dependencies = [ "GObject-2.0", "Gio-2.0", "Soup-2.4" ]
+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."Gio-2.0"]
+  name = "Gio"
+  description = "GObject interfaces and objects"
+  docs_url = "https://developer.gnome.org/gio/stable";
+
+  [dependencies."Soup-2.4"]
+  name = "Soup"
+  description = "HTTP library"
+  docs_url = "https://developer.gnome.org/libsoup/stable";
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/librest/-/blob/master/";
+
+#[extra]
+#content_files = [
+  #'json-gboxed.md',
+  #'json-gobject.md',
+  #'json-gvariant.md',
+#]
+
+#[[object]]
+#pattern = "DEPRECATED_IN_*"
+#hidden = true
+
+#[[object]]
+#name = "DEPRECATED_FOR"
+#hidden = true
+
+#[[object]]
+#name = "UNAVAILABLE"
+#hidden = true
+
+#[[object]]
+#name = "ParserError"
+  #[[object.function]]
+  #name = "quark"
+  #check_ignore = true
+
+
+#[[object]]
+#name = "PathError"
+  #[[object.function]]
+  #name = "quark"
+  #check_ignore = true
+
+#[[object]]
+#name = "ReaderError"
+  #[[object.function]]
+  #name = "quark"
+  #check_ignore = true
diff --git a/docs/meson.build b/docs/meson.build
index 164cf27..2eeb084 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -1 +1,43 @@
 subdir('reference/rest')
+
+if get_option('gtk_doc') and get_option('introspection')
+  dependency('gi-docgen', version: '>= 2021.6',
+    fallback: ['gi-docgen', 'dummy_dep'],
+  )
+
+  gidocgen = find_program('gi-docgen', required: get_option('gtk_doc'))
+
+  rest_docdir = rest_datadir / 'doc'
+
+  toml_conf = configuration_data()
+  toml_conf.set('REST_VERSION', meson.project_version())
+
+  rest_toml = configure_file(
+    input: 'librest.toml.in',
+    output: 'librest.toml',
+    configuration: toml_conf,
+  )
+
+  custom_target('librest-doc',
+    input: librest_gir[0],
+    output: 'librest-1.0',
+    command: [
+      gidocgen,
+      'generate',
+      '--quiet',
+      '--fatal-warnings',
+      '--add-include-path=@0@'.format(meson.current_build_dir() / '../rest'),
+      '--config', rest_toml,
+      '--output-dir=@OUTPUT@',
+      '--no-namespace-dir',
+      '--content-dir=@0@'.format(meson.current_source_dir()),
+      '@INPUT@',
+    ],
+    depend_files: [ rest_toml ],
+    build_by_default: true,
+    install: true,
+    install_dir: rest_docdir,
+  )
+
+endif
+
diff --git a/meson.build b/meson.build
index 469fb28..c6e77a1 100644
--- a/meson.build
+++ b/meson.build
@@ -14,6 +14,9 @@ librest_pkg_string = 'rest-@0@'.format(librest_api_version)
 gnome = import('gnome')
 pkgconfig = import('pkgconfig')
 
+# Paths
+rest_datadir = join_paths(get_option('prefix'), get_option('datadir'))
+
 # CA certificates
 if get_option('ca_certificates')
   ca_certificates_path = get_option('ca_certificates_path')
diff --git a/subprojects/gi-docgen.wrap b/subprojects/gi-docgen.wrap
new file mode 100644
index 0000000..98cd921
--- /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