15 files changed, 809 insertions, 0 deletions
diff --git a/subprojects/libhandy/doc/build-howto.xml b/subprojects/libhandy/doc/build-howto.xml
new file mode 100644
index 0000000..a6f731f
--- /dev/null
+++ b/subprojects/libhandy/doc/build-howto.xml
@@ -0,0 +1,159 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry 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;
+]>
+
+<refentry id="build-howto">
+  <refmeta>
+    <refentrytitle>Compiling with &package_string;</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>Compiling with &package_string;</refname><refpurpose>Notes on compiling.</refpurpose>
+  </refnamediv>
+
+  <refsect2>
+    <title>Building</title>
+
+    <para>
+      If you need to build <application>&package_string;</application>, get the
+      source from <ulink type="http" url="&package_url;">here</ulink> and see
+      the <literal>README.md</literal> file.
+    </para>
+  </refsect2>
+
+  <refsect2>
+    <title>Using pkg-config</title>
+
+    <para> Like other GNOME libraries,
+      <application>&package_string;</application> uses
+      <application>pkg-config</application> to provide compiler options. The
+      package name is "<literal>&package_ver_str;</literal>".
+    </para>
+
+    <para>
+      If you use Automake/Autoconf, in your <literal>configure.ac</literal>
+      script, you might specify something like:
+    </para>
+
+    <informalexample><programlisting>
+      PKG_CHECK_MODULES(LIBHANDY, [&package_ver_str;])
+      AC_SUBST(LIBHANDY_CFLAGS)
+      AC_SUBST(LIBHANDY_LIBS)
+    </programlisting></informalexample>
+
+    <para>
+      Or when using the Meson build system you can declare a dependency like:
+    </para>
+
+    <informalexample><programlisting>
+      dependency('&package_ver_str;')
+    </programlisting></informalexample>
+
+    <para>
+      The "<literal>&package_api_version;</literal>" in the package name is the
+      "API version" (indicating "the version of the <application>
+      &package_string;</application> API that first appeared in version
+      &package_api_version;") and is essentially just part of the package name.
+    </para>
+  </refsect2>
+
+  <refsect2>
+    <title>Bundling the library</title>
+
+    <para>
+      As <application>&package_string;</application> uses the Meson build
+      system, bundling it as a subproject when it is not installed is easy.
+      Add this to your <literal>meson.build</literal>:
+    </para>
+
+    <informalexample><programlisting>
+      &package_string;_dep = dependency('&package_ver_str;', version: '>= &package_version;', required: false)
+      if not &package_string;_dep.found()
+        &package_string; = subproject(
+          '&package_string;',
+          install: false,
+          default_options: [
+            'examples=false',
+            'package_subdir=my-project-name',
+            'tests=false',
+          ]
+        )
+        &package_string;_dep = &package_string;.get_variable('&package_string;_dep')
+      endif
+    </programlisting></informalexample>
+
+    <para>
+      Then add &package_string; as a git submodule:
+    </para>
+
+    <informalexample><programlisting>
+      git submodule add &package_url;.git subprojects/&package_string;
+    </programlisting></informalexample>
+
+    <para>
+      To bundle the library with your Flatpak application, add the following
+      module to your manifest:
+    </para>
+
+    <informalexample><programlisting>
+      {
+        "name" : "&package_string;",
+        "buildsystem" : "meson",
+        "builddir" : true,
+        "config-opts": [
+          "-Dexamples=false",
+          "-Dtests=false"
+        ],
+        "sources" : [
+          {
+            "type" : "git",
+            "url" : "&package_url;.git"
+          }
+        ]
+      }
+    </programlisting></informalexample>
+  </refsect2>
+
+  <refsect2>
+    <title>Building on macOS</title>
+
+    <para>
+      To build on macOS you need to install the build-dependencies first. This can e.g. be done via <ulink url="https://brew.sh"><literal>brew</literal></ulink>:
+    </para>
+
+    <informalexample>
+      <programlisting>
+        brew install pkg-config gtk+3 adwaita-icon-theme meson glade gobject-introspection vala
+      </programlisting>
+    </informalexample>
+
+    <para>
+      After running the command above, one may now build the library:
+    </para>
+
+    <informalexample>
+      <programlisting>
+        git clone https://gitlab.gnome.org/GNOME/libhandy.git
+        cd libhandy
+        meson . _build
+        ninja -C _build test
+        ninja -C _build install
+      </programlisting>
+    </informalexample>
+
+    <para>
+      Working with the library on macOS is pretty much the same as on Linux. To link it, use <literal>pkg-config</literal>:
+    </para>
+
+    <informalexample>
+      <programlisting>
+        gcc $(pkg-config --cflags --libs gtk+-3.0) $(pkg-config --cflags --libs libhandy-1) main.c -o main
+      </programlisting>
+    </informalexample>
+  </refsect2>
+</refentry>
diff --git a/subprojects/libhandy/doc/handy-docs.xml b/subprojects/libhandy/doc/handy-docs.xml
new file mode 100644
index 0000000..0bf7eab
--- /dev/null
+++ b/subprojects/libhandy/doc/handy-docs.xml
@@ -0,0 +1,140 @@
+<?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-2020</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-application-window.xml"/>
+    <xi:include href="xml/hdy-avatar.xml"/>
+    <xi:include href="xml/hdy-carousel.xml"/>
+    <xi:include href="xml/hdy-carousel-indicator-dots.xml"/>
+    <xi:include href="xml/hdy-carousel-indicator-lines.xml"/>
+    <xi:include href="xml/hdy-clamp.xml"/>
+    <xi:include href="xml/hdy-combo-row.xml"/>
+    <xi:include href="xml/hdy-deck.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-navigation-direction.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-swipe-tracker.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"/>
+    <xi:include href="xml/hdy-view-switcher-title.xml"/>
+    <xi:include href="xml/hdy-window.xml"/>
+    <xi:include href="xml/hdy-window-handle.xml"/>
+  </chapter>
+
+  <chapter id="helpers">
+    <title>Helpers</title>
+    <xi:include href="xml/hdy-version.xml"/>
+    <xi:include href="xml/hdy-main.xml"/>
+  </chapter>
+
+  <chapter id="migrating">
+    <title>Migrating from Previous Versions of Handy</title>
+
+    <xi:include href="hdy-migrating-0-0-to-1.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="api-index-1-0" role="1.0">
+    <title>Index of new symbols in 1.0</title>
+    <xi:include href="xml/api-index-1.0.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/subprojects/libhandy/doc/hdy-migrating-0-0-to-1.xml b/subprojects/libhandy/doc/hdy-migrating-0-0-to-1.xml
new file mode 100644
index 0000000..70b5e15
--- /dev/null
+++ b/subprojects/libhandy/doc/hdy-migrating-0-0-to-1.xml
@@ -0,0 +1,356 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry 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;
+]>
+
+<refentry id="hdy-migrating-0-0-to-1">
+  <refmeta>
+    <refentrytitle>Migrating from Handy 0.0.x to Handy 1</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>Migrating from Handy 0.0.x to Handy 1</refname><refpurpose>Notes on migration to Handy 1.</refpurpose>
+  </refnamediv>
+
+  <para>
+    Handy 1 is a major new version of Handy that breaks both API and ABI
+    compared to Handy 0.0.x. Thankfully, most of the changes are not hard to
+    adapt to and there are a number of steps that you can take to prepare your
+    Handy 0.0.x application for the switch to Handy 1. After that, there's a
+    number of adjustments that you may have to do when you actually switch your
+    application to build against Handy 1.
+  </para>
+
+  <refsect2>
+    <title>Preparation in Handy 0.0.x</title>
+
+    <para>
+      The steps outlined in the following sections assume that your application
+      is working with Handy 0.0.13, which is the final stable release of Handy
+      0.0.x. It includes all the necessary APIs and tools to help you port your
+      application to Handy 1. If you are using an older version of Handy 0.0.x,
+      you should first get your application to build and work with Handy 0.0.13.
+    </para>
+
+    <refsect3>
+      <title>Do not use the static build option</title>
+      <para>
+        Static linking support has been removed, and so did the static build
+        option.
+        You must adapt you program to link to the library dynamically, using
+        the package_subdir build option if needed.
+      </para>
+    </refsect3>
+
+    <refsect3>
+      <title>Do not use deprecated symbols</title>
+      <para>
+        Over the years, a number of functions, and in some cases, entire widgets
+        have been deprecated. These deprecations are clearly spelled out in the
+        API reference, with hints about the recommended replacements.
+        The API reference for GTK 3 also includes an
+        <ulink url="https://developer.puri.sm/projects/libhandy/unstable/deprecated-api-index.html">index</ulink>
+        of all deprecated symbols.
+      </para>
+    </refsect3>
+
+  </refsect2>
+
+  <refsect2>
+    <title>Changes that need to be done at the time of the switch</title>
+
+    <para>
+      This section outlines porting tasks that you need to tackle when you get
+      to the point that you actually build your application against Handy 1.
+      Making it possible to prepare for these in Handy 0.0 would have been
+      either impossible or impractical.
+    </para>
+
+    <refsect3>
+      <title>hdy_init takes no parameters</title>
+      <para>
+        hdy_init() has been modified to take no parameters.
+        It must be called just after initializing GTK, if you are using
+        #GtkApplication it means it must be called when the
+        #GApplication::startup signal is emitted.
+      </para>
+      <para>
+        It initializes the localization, the types, the themes, and the icons.
+      </para>
+    </refsect3>
+
+    <refsect3>
+      <title>Adapt to widget constructor changes</title>
+      <para>
+        All widget constructors now return the #GtkWidget type rather than the
+        constructed widget's type, following the same convention as GTK 3.
+      </para>
+      <para>
+        Affected widgets:
+        #HdyActionRow, #HdyComboRow, #HdyExpanderRow,
+        #HdyPreferencesGroup, #HdyPreferencesPage, #HdyPreferencesRow,
+        #HdyPreferencesWindow, #HdySqueezer, #HdyTitleBar, #HdyViewSwitcherBar,
+        #HdyViewSwitcher
+      </para>
+    </refsect3>
+
+    <refsect3>
+      <title>Adapt to derivability changes</title>
+      <para>
+        Some widgets are now final, if your code is deriving from them, use
+        composition instead.
+      </para>
+      <para>
+        Affected widgets:
+        #HdySqueezer, #HdyViewSwitcher, #HdyViewSwitcherBar
+      </para>
+    </refsect3>
+
+    <refsect3>
+      <title>HdyFold has been removed</title>
+      <para>
+        #HdyFold has been removed. This affects the API of #HdyLeaflet, see the
+        “Adapt to HdyLeaflet API changes” section to know how.
+      </para>
+    </refsect3>
+
+    <refsect3>
+      <title>Replace HdyColumn by HdyClamp</title>
+      <para>
+        HdyColumn has been renamed #HdyClamp as it now implements
+        #GtkOrientable, so you should replace the former by the later.
+        Its “maximum-width” and “linear-growth-width” properties have been
+        renamed #HdyClamp:maximum-size and #HdyClamp:tightening-threshold
+        respectively to better reflect their role.
+        It won't set the .narrow, .medium and .wide style classes depending on
+        its size, but the .small, .medium and .large ones instead.
+      </para>
+    </refsect3>
+
+    <refsect3>
+      <title>Adapt to HdyPaginator API changes</title>
+      <para>
+        HdyPaginator has been renamed HdyCarousel, so you should replace the
+        former by the later.
+      </para>
+      <para>
+        The “indicator-style”, “indicator-spacing” and “center-content”
+        properties have been removed, instead use #HdyCarouselIndicatorDots
+        or #HdyCarouselIndicatorLines widgets.
+      </para>
+    </refsect3>
+
+    <refsect3>
+      <title>Adapt to HdyHeaderGroup API changes</title>
+      <para>
+        The #HdyHeaderGroup object has been largely redesigned, most of its
+        methods changed, see its documentation to know more.
+      </para>
+      <para>
+        The child type is now #HdyHeaderGroupChild, which can represent either
+        a #GtkHeaderBar, a #HdyHeaderBar, or a #HdyHeaderGroup.
+      </para>
+      <para>
+        The “focus” property has been replaced by #HdyHeaderGroup:decorate-all,
+        which works quite differently.
+      </para>
+    </refsect3>
+
+    <refsect3>
+      <title>Adapt to HdyLeaflet API changes</title>
+      <para>
+        The #HdyFold type has been removed in favor of using a boolean, and
+        #HdyLeaflet adjusted to that as the #HdyLeaflet:fold property has been
+        removed in favor of #HdyLeaflet:folded.
+        Also, the hdy_leaflet_get_homogeneous() and
+        hdy_leaflet_set_homogeneous() accessors take a boolean parameter instead
+        of a #HdyFold.
+      </para>
+      <para>
+        On touchscreens, swiping forward with the “over” transition and swiping
+        back with the “under” transition can now only be done from the edge
+        where the upper child is.
+      </para>
+      <para>
+        The “over” and “under” transitions can draw their shadow on top of the
+        window's transparent areas, like the rounded corners.
+        This is a side-effect of allowing shadows to be drawn on top of OpenGL
+        areas.
+        It can be mitigated by using #HdyWindow or #HdyApplicationWindow as they
+        will crop anything drawn beyond the rounded corners.
+      </para>
+      <para>
+        The “allow-visible” child property has been renamed “navigatable”.
+      </para>
+    </refsect3>
+
+    <refsect3>
+      <title>Adapt to HdyLeaflet API changes</title>
+      <para>
+        The “none” transition type has been removed. The default value for the
+        #HdyLeaflet:transition-type property has been changed to “over”.
+        “over” is the recommended transition for typical #HdyLeaflet use-cases,
+        if this isn't what you want to use, be sure to adapt your code. If
+        transitions are undesired, set #HdyLeaflet:mode-transition-duration and
+        #HdyLeaflet:child-transition-duration properties to 0.
+      </para>
+    </refsect3>
+
+    <refsect3>
+      <title>Adapt to HdyViewSwitcher API changes</title>
+      <para>
+        #HdyViewSwitcher doesn't subclass #GtkBox anymore. Instead, it
+        subclasses #GtkBin and contains a box.
+      </para>
+      <para>
+        The “icon-size” property has been dropped without replacement, you must
+        stop using it.
+      </para>
+    </refsect3>
+
+    <refsect3>
+      <title>Adapt to HdyViewSwitcherBar API changes</title>
+      <para>
+        #HdyViewSwitcherBar won't be revealed if the #HdyViewSwitcherBar:stack
+        property is %NULL or if it has less than two pages, even if you set
+        #HdyViewSwitcherBar:reveal to %TRUE.
+      </para>
+      <para>
+        The “icon-size” property has been dropped without replacement, you must
+        stop using it.
+      </para>
+    </refsect3>
+
+    <refsect3>
+      <title>Adapt to CSS node name changes</title>
+      <para>
+        Widgets with a customn CSS node name got their name changed to be the
+        class' name in lowercase, with no separation between words, and with no
+        namespace prefix. E.g. the CSS node name of HdyViewSwitcher is
+        viewswitcher.
+      </para>
+    </refsect3>
+
+    <refsect3>
+      <title>Adapt to HdyActionRow API changes</title>
+      <para>
+        Action items were packed from the end toward the start of the row. It is
+        now reversed, and widgets have to be packed from the start to the end.
+      </para>
+      <para>
+        It isn't possible to add children at the bottom of a #HdyActionRow
+        anymore, instead use other widgets like #HdyExpanderRow.
+        Widgets added to a #HdyActionRow will now be added at the end of the
+        row, and the hdy_action_row_add_action() method and the action child
+        type have been removed.
+      </para>
+      <para>
+        The main horizontal box of #HdyActionRow had the row-header CSS style
+        class, it now has the header CSS style class and can hence be accessed
+        as box.header subnode.
+      </para>
+      <para>
+        #HdyActionRow is now unactivatable by default, giving it an activatable
+        widget will automatically make it activatable.
+      </para>
+    </refsect3>
+
+    <refsect3>
+      <title>Adapt to HdyComboRow API changes</title>
+      <para>
+        #HdyComboRow is now unactivatable by default, binding and unbinding a
+        model will toggle its activatability.
+      </para>
+    </refsect3>
+
+    <refsect3>
+      <title>Adapt to HdyExpanderRow API changes</title>
+      <para>
+        #HdyExpanderRow doesn't descend from #HdyActionRow anymore but from
+        #HdyPreferencesRow.
+        It reimplement some features from #HdyActionRow, like the
+        #HdyExpanderRow:title, #HdyExpanderRow:subtitle,
+        #HdyExpanderRow:use-underline and #HdyExpanderRow:icon-name, but it
+        doesn't offer the “activate” signal nor the ability to add widgets in
+        its header row.
+      </para>
+      <para>
+        Widgets you add to it will be added to its inner #GtkListBox.
+      </para>
+    </refsect3>
+
+    <refsect3>
+      <title>Adapt to HdyPreferencesPage API changes</title>
+      <para>
+        #HdyPreferencesPage doesn't subclass #GtkScrolledWindow anymore.
+        Instead, it subclasses #GtkBin and contains a scrolled window.
+      </para>
+    </refsect3>
+
+    <refsect3>
+      <title>Adapt to HdyPreferencesGroup API changes</title>
+      <para>
+        #HdyPreferencesGroup doesn't subclass #GtkBox anymore.
+        Instead, it subclasses #GtkBin and contains a box.
+      </para>
+    </refsect3>
+
+    <refsect3>
+      <title>Adapt to HdyKeypad API changes</title>
+      <para>
+        #HdyKeypad doesn't subclass #Gtkgrid anymore. Instead, it subclasses
+        #GtkBin and contains a grid.
+      </para>
+      <para>
+        The “show-symbols” property has been replaced by
+        #HdyHeaderGroup:letters-visible.
+      </para>
+      <para>
+        The “only-digits” property has been replaced by
+        #HdyHeaderGroup:symbols-visible, which has a inverse boolean meaning.
+        This also affects the corresponding parameter of the constructor.
+      </para>
+      <para>
+        The “left-action” property has been replaced by
+        #HdyHeaderGroup:start-action, and the “right-action” property has been
+        replaced by #HdyHeaderGroup:end-action.
+      </para>
+      <para>
+        The “entry” property isn't a #GtkWidget anymore but a #GtkEntry.
+      </para>
+    </refsect3>
+
+    <refsect3>
+      <title>Stop using hdy_list_box_separator_header()</title>
+      <para>
+        Instead, either use CSS styling (the list.content style class may
+        fit your need), or implement it yourself as it is trivial.
+      </para>
+    </refsect3>
+
+    <refsect3>
+      <title>Stop acknowledging the Instability</title>
+      <para>
+        When the library was young and changing a lot, we required you to
+        acknowledge that your are using an unstable API. To do so, you had to
+        define <literal>HANDY_USE_UNSTABLE_API</literal> for compilation to
+        succeed.
+      </para>
+      <para>
+        The API remained stable since many versions, despite this acknowlegment
+        still being required. To reflect that proven stability, the
+        acknowlegment isn't necessary and you can stop defining
+        <literal>HANDY_USE_UNSTABLE_API</literal>, either before including the
+        &package_string; header in C-compatible languages, or with the
+        definition option of your compiler.
+      </para>
+    </refsect3>
+
+  </refsect2>
+
+</refentry>
+
diff --git a/subprojects/libhandy/doc/images/avatar.png b/subprojects/libhandy/doc/images/avatar.png
new file mode 100644
index 0000000..07a156f
--- /dev/null
+++ b/subprojects/libhandy/doc/images/avatar.png
diff --git a/subprojects/libhandy/doc/images/header-bar.png b/subprojects/libhandy/doc/images/header-bar.png
new file mode 100644
index 0000000..c15b1f6
--- /dev/null
+++ b/subprojects/libhandy/doc/images/header-bar.png
diff --git a/subprojects/libhandy/doc/images/keypad.png b/subprojects/libhandy/doc/images/keypad.png
new file mode 100644
index 0000000..6bc18d5
--- /dev/null
+++ b/subprojects/libhandy/doc/images/keypad.png
diff --git a/subprojects/libhandy/doc/images/list.png b/subprojects/libhandy/doc/images/list.png
new file mode 100644
index 0000000..e02833c
--- /dev/null
+++ b/subprojects/libhandy/doc/images/list.png
diff --git a/subprojects/libhandy/doc/images/preferences-window.png b/subprojects/libhandy/doc/images/preferences-window.png
new file mode 100644
index 0000000..bd696a7
--- /dev/null
+++ b/subprojects/libhandy/doc/images/preferences-window.png
diff --git a/subprojects/libhandy/doc/images/search.png b/subprojects/libhandy/doc/images/search.png
new file mode 100644
index 0000000..38d14ef
--- /dev/null
+++ b/subprojects/libhandy/doc/images/search.png
diff --git a/subprojects/libhandy/doc/images/view-switcher-bar.png b/subprojects/libhandy/doc/images/view-switcher-bar.png
new file mode 100644
index 0000000..3a0836d
--- /dev/null
+++ b/subprojects/libhandy/doc/images/view-switcher-bar.png
diff --git a/subprojects/libhandy/doc/images/view-switcher.png b/subprojects/libhandy/doc/images/view-switcher.png
new file mode 100644
index 0000000..b8727df
--- /dev/null
+++ b/subprojects/libhandy/doc/images/view-switcher.png
diff --git a/subprojects/libhandy/doc/meson.build b/subprojects/libhandy/doc/meson.build
new file mode 100644
index 0000000..eeab57a
--- /dev/null
+++ b/subprojects/libhandy/doc/meson.build
@@ -0,0 +1,75 @@
+if get_option('gtk_doc')
+
+subdir('xml')
+
+private_headers = [
+    'config.h',
+    'gtkprogresstrackerprivate.h',
+    'gtk-window-private.h',
+    'hdy-animation-private.h',
+    'hdy-carousel-box-private.h',
+    'hdy-css-private.h',
+    'hdy-enums.h',
+    'hdy-enums-private.h',
+    'hdy-main-private.h',
+    'hdy-nothing-private.h',
+    'hdy-keypad-button-private.h',
+    'hdy-preferences-group-private.h',
+    'hdy-preferences-page-private.h',
+    'hdy-shadow-helper-private.h',
+    'hdy-stackable-box-private.h',
+    'hdy-swipe-tracker-private.h',
+    'hdy-types.h',
+    'hdy-view-switcher-button-private.h',
+    'hdy-window-handle-controller-private.h',
+    'hdy-window-mixin-private.h',
+]
+
+images = [
+  'images/avatar.png',
+  'images/header-bar.png',
+  'images/keypad.png',
+  'images/list.png',
+  'images/preferences-window.png',
+  'images/search.png',
+  'images/view-switcher.png',
+  'images/view-switcher-bar.png',
+]
+
+content_files = [
+  'build-howto.xml',
+  'hdy-migrating-0-0-to-1.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('libhandy',
+           main_xml: 'handy-docs.xml',
+            src_dir: [
+                       meson.source_root() / 'src',
+                       meson.build_root()  / 'src',
+                     ],
+       dependencies: libhandy_dep,
+  gobject_typesfile: 'libhandy.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'),
+                       '--extra-dir=@0@'.format(glib_docpath / 'gdk-pixbuf'),
+                     ],
+        install_dir: 'libhandy-' + apiversion,
+      content_files: content_files,
+        html_assets: images,
+            install: true)
+
+endif
diff --git a/subprojects/libhandy/doc/visual-index.xml b/subprojects/libhandy/doc/visual-index.xml
new file mode 100644
index 0000000..1648608
--- /dev/null
+++ b/subprojects/libhandy/doc/visual-index.xml
@@ -0,0 +1,58 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry 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;
+]>
+
+<refentry id="visual-index">
+  <refmeta>
+    <refentrytitle>Visual index</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+  <refnamediv>
+    <refname>Widgets in &package_string;</refname><refpurpose>Widget overview.</refpurpose>
+  </refnamediv>
+
+  <refsect2>
+    <title>Widgets</title>
+    <para role="gallery">
+      <link linkend="HdyAvatar">
+        <inlinegraphic fileref="avatar.png" format="PNG"></inlinegraphic>
+      </link>
+    </para>
+    <para role="gallery">
+      <link linkend="HdyKeypad">
+        <inlinegraphic fileref="keypad.png" format="PNG"></inlinegraphic>
+      </link>
+    </para>
+    <para role="gallery">
+      <link>
+        <inlinegraphic fileref="list.png" format="PNG" scale="60"></inlinegraphic>
+      </link>
+      <link linkend="HdySearchBar">
+        <inlinegraphic fileref="search.png" format="PNG"></inlinegraphic>
+      </link>
+    </para>
+    <para role="gallery">
+      <link linkend="HdyHeaderBar">
+        <inlinegraphic fileref="header-bar.png" format="PNG"></inlinegraphic>
+      </link>
+      <link linkend="HdyPreferencesWindow">
+        <inlinegraphic fileref="preferences-window.png" format="PNG"></inlinegraphic>
+      </link>
+    </para>
+  </refsect2>
+  <refsect2>
+    <title>HdyViewSwitcher</title>
+    <para role="gallery">
+      <link linkend="HdyViewSwitcher">
+        <inlinegraphic fileref="view-switcher.png" format="PNG"></inlinegraphic>
+      </link>
+      <link linkend="HdyViewSwitcherBar">
+        <inlinegraphic fileref="view-switcher-bar.png" format="PNG"></inlinegraphic>
+      </link>
+    </para>
+  </refsect2>
+</refentry>
diff --git a/subprojects/libhandy/doc/xml/gtkdocentities.ent.in b/subprojects/libhandy/doc/xml/gtkdocentities.ent.in
new file mode 100644
index 0000000..45d322c
--- /dev/null
+++ b/subprojects/libhandy/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/subprojects/libhandy/doc/xml/meson.build b/subprojects/libhandy/doc/xml/meson.build
new file mode 100644
index 0000000..5f73097
--- /dev/null
+++ b/subprojects/libhandy/doc/xml/meson.build
@@ -0,0 +1,12 @@
+ent_conf = configuration_data()
+ent_conf.set('PACKAGE', 'Handy')
+ent_conf.set('PACKAGE_BUGREPORT', 'https://gitlab.gnome.org/GNOME/libhandy/issues')
+ent_conf.set('PACKAGE_NAME', 'Handy')
+ent_conf.set('PACKAGE_STRING', 'libhandy')
+ent_conf.set('PACKAGE_TARNAME', 'libhandy-' + meson.project_version())
+ent_conf.set('PACKAGE_URL', 'https://gitlab.gnome.org/GNOME/libhandy')
+ent_conf.set('PACKAGE_VERSION', meson.project_version())
+ent_conf.set('PACKAGE_API_VERSION', apiversion)
+ent_conf.set('PACKAGE_API_NAME', package_api_name)
+configure_file(input: 'gtkdocentities.ent.in', output: 'gtkdocentities.ent', configuration: ent_conf)
+