GNOME.org
 

[retro-gtk/build-doc] WIP: Add, build and deploy the reference manual

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

    WIP: Add, build and deploy the reference manual

 .gitlab-ci.yml                         |  37 ++++++++++-
 doc/meson.build                        |  69 +++++++++++++++++++
 doc/retro-gtk-doc.xml                  | 118 +++++++++++++++++++++++++++++++++
 doc/xml/gtkdocentities.ent.in          |   9 +++
 doc/xml/meson.build                    |  12 ++++
 flatpak/org.gnome.Retro.Reference.json |  56 ++++++++++++++++
 meson.build                            |  17 +++--
 meson_options.txt                      |   4 ++
 8 files changed, 314 insertions(+), 8 deletions(-)
---
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index d345391..2c97e97 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -3,6 +3,7 @@ stages:
   - build
   - test
   - review
+  - publish
 
 api-visibility:
   stage: lint
@@ -35,7 +36,7 @@ flatpak:tests:
     MANIFEST_PATH: "flatpak/org.gnome.Retro.UnitTests.json"
     FLATPAK_MODULE: "retro-gtk"
     FLATPAK_BUILD_DIR: "unit-tests"
-    MESON_ARGS: "--libdir=lib -Dinstall-tests=true -Dpulseaudio=disabled"
+    MESON_ARGS: "--libdir=lib -Dinstall-tests=true -Dpulseaudio=disabled -Dbuild-doc=false"
   script:
     - flatpak-builder --user --disable-rofiles-fuse --stop-at=${FLATPAK_MODULE} ${FLATPAK_BUILD_DIR} 
${MANIFEST_PATH}
     - flatpak build ${FLATPAK_BUILD_DIR} meson --prefix=/app ${MESON_ARGS} _build_tests
@@ -53,7 +54,7 @@ flatpak:demo:
     RUNTIME_REPO: "https://sdk.gnome.org/gnome-nightly.flatpakrepo";
     FLATPAK_MODULE: "retro-gtk"
     FLATPAK_BUILD_DIR: "app"
-    MESON_ARGS: ""
+    MESON_ARGS: "-Dbuild-doc=false"
   script:
     - flatpak-builder --user --disable-rofiles-fuse --stop-at=${FLATPAK_MODULE} ${FLATPAK_BUILD_DIR} 
${MANIFEST_PATH}
     - flatpak build ${FLATPAK_BUILD_DIR} meson --prefix=/app ${MESON_ARGS} _build
@@ -66,10 +67,32 @@ flatpak:demo:
       - _build/meson-logs/meson-log.txt
     expire_in: 2 days
 
+flatpak:reference:
+  image: registry.gitlab.gnome.org/gnome/gnome-runtime-images/gnome:master
+  stage: build
+  tags:
+    - flatpak
+  variables:
+    MANIFEST_PATH: "flatpak/org.gnome.Retro.Reference.json"
+    FLATPAK_MODULE: "retro-gtk"
+    FLATPAK_BUILD_DIR: "app"
+    MESON_ARGS: "-Ddemos=false -Dbuild-tests=false -Dbuild-doc=true"
+  script:
+    - flatpak-builder --stop-at=${FLATPAK_MODULE} ${FLATPAK_BUILD_DIR} ${MANIFEST_PATH}
+    - flatpak build ${FLATPAK_BUILD_DIR} meson --prefix=/app ${MESON_ARGS} _build
+    - flatpak build ${FLATPAK_BUILD_DIR} ninja -C _build
+    - flatpak build ${FLATPAK_BUILD_DIR} ninja -C _build retro-gtk-doc 2>&1 | tee _build/doc/buildlog
+    - if grep -qs 'warning' _build/doc/buildlog; then exit 1; fi
+    - mv _build/doc/html/ _reference/
+  artifacts:
+    paths:
+      - _reference
+
 review:
   stage: review
   dependencies:
     - flatpak:demo
+    - flatpak:reference
     - flatpak:tests
   script:
     - echo "Generating flatpak deployment"
@@ -98,3 +121,13 @@ stop_review:
     - master@GNOME/retro-gtk
     - gnome-3-.*
     - tags
+
+pages:
+  stage: publish
+  script:
+    - mv _reference/ public/
+  artifacts:
+    paths:
+      - public
+  only:
+    - master
diff --git a/doc/meson.build b/doc/meson.build
new file mode 100644
index 0000000..df121fc
--- /dev/null
+++ b/doc/meson.build
@@ -0,0 +1,69 @@
+subdir('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'
+# docpath = get_option('datadir') / 'retro-gtk-doc' / 'html'
+
+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',
+]
+
+gnome.gtkdoc(
+  'retro-gtk',
+  main_xml: 'retro-gtk-doc.xml',
+  src_dir: [
+    meson.source_root() / 'retro-gtk',
+    meson.build_root()  / 'retro-gtk',
+    meson.source_root() / 'shared',
+    meson.build_root()  / 'shared',
+  ],
+  dependencies: retro_gtk_dep,
+  gobject_typesfile: 'retro-gtk.types',
+  scan_args: [
+    '--rebuild-types',
+    '--ignore-headers=' + ' '.join(private_headers),
+  ],
+  mkdb_args: [
+    '--default-includes=retro-gtk/retro-gtk.h',
+  ],
+  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'),
+    '--extra-dir=@0@'.format(glib_docpath / 'gdk-pixbuf'),
+  ],
+  install_dir: 'retro-gtk',
+  content_files: content_files,
+  install: get_option('install-doc'),
+)
diff --git a/doc/retro-gtk-doc.xml b/doc/retro-gtk-doc.xml
new file mode 100644
index 0000000..214c39a
--- /dev/null
+++ b/doc/retro-gtk-doc.xml
@@ -0,0 +1,118 @@
+<?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;">RetroGTK</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>2014-2020</year>
+      <holder>Adrien Plazas</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/retro-controller-codes.xml"/>
+    <xi:include href="xml/retro-controller-iterator.xml"/>
+    <xi:include href="xml/retro-controller-type.xml"/>
+    <xi:include href="xml/retro-controller.xml"/>
+    <xi:include href="xml/retro-core-descriptor.xml"/>
+    <xi:include href="xml/retro-core-view.xml"/>
+    <xi:include href="xml/retro-core.xml"/>
+    <xi:include href="xml/retro-input.xml"/>
+    <xi:include href="xml/retro-key-joypad-mapping.xml"/>
+    <xi:include href="xml/retro-log.xml"/>
+    <xi:include href="xml/retro-memory-type.xml"/>
+    <xi:include href="xml/retro-module-iterator.xml"/>
+    <xi:include href="xml/retro-module-query.xml"/>
+    <xi:include href="xml/retro-option-iterator.xml"/>
+    <xi:include href="xml/retro-option.xml"/>
+    <xi:include href="xml/retro-pixbuf.xml"/>
+    <xi:include href="xml/retro-pixdata.xml"/>
+    <xi:include href="xml/retro-rumble-effect.xml"/>
+    <xi:include href="xml/retro-video-filter.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/doc/xml/gtkdocentities.ent.in b/doc/xml/gtkdocentities.ent.in
new file mode 100644
index 0000000..45d322c
--- /dev/null
+++ b/doc/xml/gtkdocentities.ent.in
@@ -0,0 +1,9 @@
+<!ENTITY package "@PACKAGE@">
+<!ENTITY package_bugreport "@PACKAGE_BUGREPORT@">
+<!ENTITY package_name "@PACKAGE_NAME@">
+<!ENTITY package_string "@PACKAGE_STRING@">
+<!ENTITY package_tarname "@PACKAGE_TARNAME@">
+<!ENTITY package_url "@PACKAGE_URL@">
+<!ENTITY package_version "@PACKAGE_VERSION@">
+<!ENTITY package_api_version "@PACKAGE_API_VERSION@">
+<!ENTITY package_ver_str "@PACKAGE_API_NAME@">
diff --git a/doc/xml/meson.build b/doc/xml/meson.build
new file mode 100644
index 0000000..78bc2bc
--- /dev/null
+++ b/doc/xml/meson.build
@@ -0,0 +1,12 @@
+ent_conf = configuration_data()
+ent_conf.set('PACKAGE', 'retro-gtk')
+ent_conf.set('PACKAGE_BUGREPORT', 'https://gitlab.gnome.org/GNOME/retro-gtk/issues')
+ent_conf.set('PACKAGE_NAME', 'retro-gtk')
+ent_conf.set('PACKAGE_STRING', 'retro-gtk')
+ent_conf.set('PACKAGE_TARNAME', 'retro-gtk-' + retro_gtk_version)
+ent_conf.set('PACKAGE_URL', 'https://gitlab.gnome.org/GNOME/retro-gtk')
+ent_conf.set('PACKAGE_VERSION', retro_gtk_version)
+ent_conf.set('PACKAGE_API_VERSION', retro_gtk_api_version)
+ent_conf.set('PACKAGE_API_NAME', retro_gtk_module)
+configure_file(input: 'gtkdocentities.ent.in', output: 'gtkdocentities.ent', configuration: ent_conf)
+
diff --git a/flatpak/org.gnome.Retro.Reference.json b/flatpak/org.gnome.Retro.Reference.json
new file mode 100644
index 0000000..aaa2882
--- /dev/null
+++ b/flatpak/org.gnome.Retro.Reference.json
@@ -0,0 +1,56 @@
+{
+    "app-id" : "org.gnome.Retro.DemoSamplesTest",
+    "runtime" : "org.gnome.Platform",
+    "runtime-version" : "master",
+    "sdk" : "org.gnome.Sdk",
+    "command" : "retro-demo",
+    "tags" : [
+        "devel",
+        "development",
+        "nightly"
+    ],
+    "desktop-file-name-suffix" : " (Development)",
+    "finish-args" : [
+        /* GTK+ Inspector access */
+        "--env=DCONF_USER_CONFIG_DIR=.config/dconf",
+        /* X11 + XShm access */
+        "--share=ipc",
+        "--socket=x11",
+        /* Wayland access */
+        "--socket=wayland",
+        /* PulseAudio access */
+        "--device=dri",
+        "--socket=pulseaudio"
+    ],
+    "cleanup" : [
+        "/include",
+        "/lib/pkgconfig",
+        "/share/pkgconfig",
+        "/share/aclocal",
+        "/man",
+        "/share/man",
+        "/share/gtk-doc",
+        "*.la",
+        "*.a",
+        "/lib/girepository-1.0",
+        "/share/dbus-1",
+        "/share/doc",
+        "/share/gir-1.0"
+    ],
+    "modules" : [
+        {
+            "name" : "retro-gtk",
+            "buildsystem" : "meson",
+            "builddir" : true,
+            "config-opts" : [
+                "--libdir=lib"
+            ],
+            "sources" : [
+                {
+                    "type" : "git",
+                    "url" : "https://gitlab.gnome.org/GNOME/retro-gtk.git";
+                }
+            ]
+        }
+    ]
+}
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..476e8f0 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: 'true',
+  description : 'Install API reference documentation')
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]