[retro-gtk/build-doc: 22/23] build documentation

[Adrien Plazas <aplazas src gnome org>]

commit e027fc055425c982c8e1fc70e8e2928e2a72f1fe
Author: Adrien Plazas <kekun plazas laposte net>
Date:   Mon Jan 20 18:50:14 2020 +0100

    build documentation

 .gitlab-ci.yml        |  14 ++++++
 doc/meson.build       |  64 +++++++++++++++++++++++++
 doc/retro-gtk-doc.xml | 127 ++++++++++++++++++++++++++++++++++++++++++++++++++
 meson.build           |  17 ++++---
 meson_options.txt     |   4 ++
 5 files changed, 220 insertions(+), 6 deletions(-)
---
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index f1ab8dc..74c5cc2 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -1,6 +1,7 @@
 stages:
   - lint
   - build
+  - doc
   - test
   - review
 
@@ -68,6 +69,19 @@ flatpak:demo:
     paths:
       - .flatpak-builder/cache/
 
+build-doc:
+  image: debian:buster
+  stage: docs
+  dependencies:
+    - build-debian-gcc
+  script:
+    - ninja -C _build meson-libhandy-doc 2>&1 | tee _build/doc/buildlog
+    - if grep -qs 'warning' _build/doc/buildlog; then exit 1; fi
+  artifacts:
+    when: always
+    paths:
+      - _build/doc/html
+
 review:
   stage: review
   dependencies:
diff --git a/doc/meson.build b/doc/meson.build
new file mode 100644
index 0000000..65f3a43
--- /dev/null
+++ b/doc/meson.build
@@ -0,0 +1,64 @@
+
+# subdir('xml')
+
+private_headers = [
+  'retro-cairo-display-private.h',
+  'retro-controller-iterator-private.h',
+  'retro-core-private.h',
+  'retro-core-view-controller-private.h',
+  'retro-disk-control-callback-private.h',
+  'retro-game-info-private.h',
+  'retro-gl-display-private.h',
+  'retro-glsl-filter-private.h',
+  'retro-input-descriptor-private.h',
+  'retro-input-private.h',
+  'retro-keyboard-key-private.h',
+  'retro-keyboard-private.h',
+  'retro-module-private.h',
+  'retro-option-iterator-private.h',
+  'retro-option-private.h',
+  'retro-pa-player-private.h',
+  'retro-pixdata-private.h',
+  'retro-pixel-format-private.h',
+  'retro-rotation-private.h',
+  'retro-system-av-info-private.h',
+  'retro-system-info-private.h',
+  'retro-variable-private.h',
+]
+
+# content_files = [
+#   'build-howto.xml',
+#   'visual-index.xml',
+# ]
+
+
+glib_prefix = dependency('glib-2.0').get_pkgconfig_variable('prefix')
+glib_docpath = glib_prefix / 'share' / 'gtk-doc' / 'html'
+docpath = get_option('datadir') / 'gtk-doc' / 'html'
+
+gnome.gtkdoc(
+  'retro-gtk',
+  main_xml: 'retro-gtk-doc.xml',
+  src_dir: [
+    meson.source_root() / 'retro-gtk',
+    meson.build_root()  / 'retro-gtk',
+  ],
+  # dependencies: retro_gtk_dep,
+  # gobject_typesfile: 'retro-gtk.types',
+  # scan_args: [
+  #   '--rebuild-types',
+  #   '--ignore-headers=' + ' '.join(private_headers),
+  # ],
+  # fixxref_args: [
+  #   '--html-dir=@0@'.format(docpath),
+  #   '--extra-dir=@0@'.format(glib_docpath / 'glib'),
+  #   '--extra-dir=@0@'.format(glib_docpath / 'gobject'),
+  #   '--extra-dir=@0@'.format(glib_docpath / 'gio'),
+  #   '--extra-dir=@0@'.format(glib_docpath / 'gi'),
+  #   '--extra-dir=@0@'.format(glib_docpath / 'gtk3'),
+  # ],
+  install_dir: 'retro-gtk',
+  # content_files: content_files,
+  install: get_option('install-tests'),
+)
+
diff --git a/doc/retro-gtk-doc.xml b/doc/retro-gtk-doc.xml
new file mode 100644
index 0000000..78374d0
--- /dev/null
+++ b/doc/retro-gtk-doc.xml
@@ -0,0 +1,127 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd";
+[
+  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+  <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
+  %gtkdocentities;
+]>
+<book id="index">
+  <bookinfo>
+    <title>&package_name; Reference Manual</title>
+    <releaseinfo>
+      <para>This document is the API reference for &package_name; &package_version;.</para>
+      <para>
+        <ulink type="http" url="&package_url;">Handy</ulink> is a library to help you write apps for 
GTK/GNOME based mobile phones.
+      </para>
+      <para>
+        If you find any issues in this API reference, please report it using
+        <ulink type="http" url="&package_bugreport;">the bugtracker</ulink>.
+      </para>
+    </releaseinfo>
+
+    <copyright>
+      <year>2017-2019</year>
+      <holder>Purism SPC</holder>
+    </copyright>
+  </bookinfo>
+
+  <chapter id="intro">
+    <title>Introduction</title>
+
+    <xi:include href="build-howto.xml"/>
+    <xi:include href="visual-index.xml"/>
+  </chapter>
+
+  <chapter id="core-api">
+    <title>Widgets and Objects</title>
+    <xi:include href="xml/hdy-action-row.xml"/>
+    <xi:include href="xml/hdy-animation.xml"/>
+    <xi:include href="xml/hdy-arrows.xml"/>
+    <xi:include href="xml/hdy-column.xml"/>
+    <xi:include href="xml/hdy-combo-row.xml"/>
+    <xi:include href="xml/hdy-dialer.xml"/>
+    <xi:include href="xml/hdy-dialer-button.xml"/>
+    <xi:include href="xml/hdy-dialer-cycle-button.xml"/>
+    <xi:include href="xml/hdy-dialog.xml"/>
+    <xi:include href="xml/hdy-enum-value-object.xml"/>
+    <xi:include href="xml/hdy-expander-row.xml"/>
+    <xi:include href="xml/hdy-header-bar.xml"/>
+    <xi:include href="xml/hdy-header-group.xml"/>
+    <xi:include href="xml/hdy-keypad.xml"/>
+    <xi:include href="xml/hdy-leaflet.xml"/>
+    <xi:include href="xml/hdy-paginator.xml"/>
+    <xi:include href="xml/hdy-preferences-group.xml"/>
+    <xi:include href="xml/hdy-preferences-page.xml"/>
+    <xi:include href="xml/hdy-preferences-row.xml"/>
+    <xi:include href="xml/hdy-preferences-window.xml"/>
+    <xi:include href="xml/hdy-search-bar.xml"/>
+    <xi:include href="xml/hdy-squeezer.xml"/>
+    <xi:include href="xml/hdy-swipeable.xml"/>
+    <xi:include href="xml/hdy-swipe-group.xml"/>
+    <xi:include href="xml/hdy-title-bar.xml"/>
+    <xi:include href="xml/hdy-value-object.xml"/>
+    <xi:include href="xml/hdy-view-switcher.xml"/>
+    <xi:include href="xml/hdy-view-switcher-bar.xml"/>
+  </chapter>
+
+  <chapter id="helpers">
+    <title>Helpers</title>
+    <xi:include href="xml/hdy-version.xml"/>
+    <xi:include href="xml/hdy-main.xml"/>
+    <xi:include href="xml/hdy-string-utf8.xml"/>
+    <xi:include href="xml/hdy-fold.xml"/>
+    <xi:include href="xml/hdy-list-box.xml"/>
+  </chapter>
+
+  <chapter id="object-tree">
+    <title>Object Hierarchy</title>
+    <xi:include href="xml/tree_index.sgml"/>
+  </chapter>
+
+  <index id="api-index-full">
+    <title>API Index</title>
+    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+  </index>
+
+  <index id="deprecated-api-index" role="deprecated">
+    <title>Index of deprecated API</title>
+    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+  </index>
+
+  <index id="api-index-0-0-6" role="0.0.6">
+    <title>Index of new symbols in 0.0.6</title>
+    <xi:include href="xml/api-index-0.0.6.xml"><xi:fallback /></xi:include>
+  </index>
+
+  <index id="api-index-0-0-7" role="0.0.7">
+    <title>Index of new symbols in 0.0.7</title>
+    <xi:include href="xml/api-index-0.0.7.xml"><xi:fallback /></xi:include>
+  </index>
+
+  <index id="api-index-0-0-8" role="0.0.8">
+    <title>Index of new symbols in 0.0.8</title>
+    <xi:include href="xml/api-index-0.0.8.xml"><xi:fallback /></xi:include>
+  </index>
+
+  <index id="api-index-0-0-10" role="0.0.10">
+    <title>Index of new symbols in 0.0.10</title>
+    <xi:include href="xml/api-index-0.0.10.xml"><xi:fallback /></xi:include>
+  </index>
+
+  <index id="api-index-0-0-11" role="0.0.11">
+    <title>Index of new symbols in 0.0.11</title>
+    <xi:include href="xml/api-index-0.0.11.xml"><xi:fallback /></xi:include>
+  </index>
+
+  <index id="api-index-0-0-12" role="0.0.12">
+    <title>Index of new symbols in 0.0.12</title>
+    <xi:include href="xml/api-index-0.0.12.xml"><xi:fallback /></xi:include>
+  </index>
+
+  <index id="annotations-glossary">
+  <title>Annotations glossary</title>
+  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+  </index>
+
+</book>
diff --git a/meson.build b/meson.build
index 58db859..aafcd78 100644
--- a/meson.build
+++ b/meson.build
@@ -50,6 +50,9 @@ subdir('retro-gtk')
 if get_option('build-tests')
   subdir('tests')
 endif
+if get_option('build-doc')
+  subdir('doc')
+endif
 if get_option('demos')
   subdir('demos')
 endif
@@ -59,13 +62,15 @@ summary = [
   '------',
   'retro-gtk @0@ (@1@)'.format(retro_gtk_version, retro_gtk_api_version),
   '',
-  '     Introspection: @0@'.format(get_option('introspection')),
-  '       Build tests: @0@'.format(get_option('build-tests')),
-  '     Install tests: @0@'.format(get_option('install-tests')),
-  '             Demos: @0@'.format(get_option('demos')),
+  '           Introspection: @0@'.format(get_option('introspection')),
+  '             Build tests: @0@'.format(get_option('build-tests')),
+  '           Install tests: @0@'.format(get_option('install-tests')),
+  '     Build documentation: @0@'.format(get_option('build-doc')),
+  '   Install documentation: @0@'.format(get_option('install-doc')),
+  '                   Demos: @0@'.format(get_option('demos')),
   'Directories:',
-  '            prefix: @0@'.format(retro_gtk_prefix),
-  '           datadir: @0@'.format(retro_gtk_datadir),
+  '                  prefix: @0@'.format(retro_gtk_prefix),
+  '                 datadir: @0@'.format(retro_gtk_datadir),
   '------',
   ''
 ]
diff --git a/meson_options.txt b/meson_options.txt
index de6899b..aa529e5 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -13,4 +13,8 @@ option('build-tests', type: 'boolean', value: 'true',
   description : 'Build tests')
 option('install-tests', type: 'boolean', value: 'false',
   description : 'Install tests')
+option('build-doc', type: 'boolean', value: 'true',
+  description : 'Build API reference documentation')
+option('install-doc', type: 'boolean', value: 'false',
+  description : 'Install API reference documentation')