Port to gi-docgen

The file  was not used anywhere docs/reference/client-howto.xml.

19 files changed, 820 insertions, 2695 deletions

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index f2b61d9d..b7aefaaa 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -86,28 +86,27 @@ fedora-asan:
 reference:
   stage: docs
   variables:
-    DESTDIR: _install
-  needs: []
+    MESON_ARGS: >-
+      -Dgtk_doc=true
+      -Dvapi=disabled
   script:
-    - meson _build --prefix=/usr -Dgtk_doc=true
-    - ninja -C _build libsoup-3.0-doc
-    - .gitlab-ci/check-docs.py
     - mkdir -p _reference/libsoup-3.0
-    - cp -R _build/docs/reference/html/* _reference/libsoup-3.0/
-    - cp -R /usr/share/gtk-doc/html/{glib,gio,gobject,libsoup-2.4} _reference
-    - cp .gitlab-ci/index.html _reference
-    - gtkdoc-rebase --relative --html-dir=./_reference/ --verbose
+    - meson ${MESON_ARGS} _build
+    - ninja -C _build
+    - mv _build/docs/reference/libsoup-3.0/* _reference/libsoup-3.0
+    # Add libsoup-2.4 docs.
+    - cp -R /usr/share/gtk-doc/html/{glib,gio,gobject,libsoup-2.4} _reference/
+    - cp .gitlab-ci/index.html _reference/
   artifacts:
     paths:
-      - _build/docs/reference/libsoup-3.0-*.txt
       - _reference
-  coverage: '/^([\d]+\%) symbol docs coverage\.\s+/'
 
 pages:
   stage: deploy
   needs: ['reference']
   script:
-    - mv _reference/ public/
+    - mv _reference public
   artifacts:
+    when: on_success
     paths:
       - public
diff --git a/.gitlab-ci/check-docs.py b/.gitlab-ci/check-docs.py
deleted file mode 100755
index 8d432df7..00000000
--- a/.gitlab-ci/check-docs.py
+++ /dev/null
@@ -1,24 +0,0 @@
-#!/usr/bin/env python3
-
-import sys
-
-with open('_build/docs/reference/libsoup-3.0-unused.txt') as f:
-    unused_docs = f.read()
-
-if unused_docs:
-    print('There is documentation not listed in libsoup-3.0-sections.txt:')
-    print(unused_docs)
-    sys.exit(1)
-
-with open('_build/docs/reference/libsoup-3.0-undocumented.txt') as f:
-    # The file starts with a summary
-    # undocumented_summary = ''.join(f.readline() for i in range(6)).strip()
-    print(f.readline()) # e.g. 95% symbol docs coverage.
-    for i in range(4):
-        f.readline()
-    undocumented_list = f.read().strip()
-
-if undocumented_list:
-    print('There is missing documentation for these symbols:')
-    print(undocumented_list)
-    sys.exit(1)
diff --git a/docs/reference/build-howto.md b/docs/reference/build-howto.md
new file mode 100644
index 00000000..366dec36
--- /dev/null
+++ b/docs/reference/build-howto.md
@@ -0,0 +1,68 @@
+Title: Building with libsoup
+Slug: build-howto
+
+# Building with libsoup
+
+## Buildsystem Integration
+
+Like other GNOME libraries, libsoup uses
+`pkg-config` to provide compiler options. The package
+name is `libsoup-3.0`. For example if you use Autotools:
+
+```
+PKG_CHECK_MODULES(LIBSOUP, [libsoup-3.0])
+AC_SUBST(LIBSOUP_CFLAGS)
+AC_SUBST(LIBSOUP_LIBS)
+```
+
+If you use Meson: 
+
+```
+libsoup_dep = dependency('libsoup-3.0')
+```
+    
+## API Availability and Deprecation Warnings
+
+If you want to restrict your program to a particular libsoup version or range of
+versions, you can define [const@VERSION_MIN_REQUIRED] and/or
+`SOUP_VERSION_MAX_ALLOWED`. For example with Autotools:
+
+```
+LIBSOUP_CFLAGS="$LIBSOUP_CFLAGS -DSOUP_VERSION_MIN_REQUIRED=SOUP_VERSION_3_0"
+LIBSOUP_CFLAGS="$LIBSOUP_CFLAGS -DSOUP_VERSION_MAX_ALLOWED=SOUP_VERSION_3_2"
+```
+
+Or with Meson:
+
+```meson
+add_project_arguments(
+  '-DSOUP_VERSION_MIN_REQUIRED=SOUP_VERSION_2_99',
+  '-DSOUP_VERSION_MAX_ALLOWED=SOUP_VERSION_3_0',
+  language: 'c'
+)
+```
+  
+The [const@VERSION_MIN_REQUIRED] declaration states that the code is not
+expected to compile on versions of libsoup older than the indicated version, and
+so the compiler should print warnings if the code uses functions that were
+deprecated as of that release.
+
+The `SOUP_VERSION_MAX_ALLOWED` declaration states that the code *is* expected
+to compile on versions of libsoup up to the indicated version, and so, when
+compiling the program against a newer version than that, the compiler should
+print warnings if the code uses functions that did not yet exist in the
+max-allowed release.
+
+You can use [func@CHECK_VERSION] to check the version of libsoup at compile
+time, to compile different code for different libsoup versions. (If you are
+setting [const@VERSION_MIN_REQUIRED] and `SOUP_VERSION_MAX_ALLOWED` to
+different versions, as in the example above, then you almost certainly need to
+be doing this.)
+  
+## Headers
+
+Code using libsoup should include the header like so:
+
+```c
+#include <libsoup/soup.h>
+```
diff --git a/docs/reference/build-howto.xml b/docs/reference/build-howto.xml
deleted file mode 100644
index b54697f4..00000000
--- a/docs/reference/build-howto.xml
+++ /dev/null
@@ -1,70 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="http://docbook.org/xml/5.1/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
-<?xml-model href="http://docbook.org/xml/5.1/sch/docbook.sch" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>
-<sect1 xmlns="http://docbook.org/ns/docbook" 
-    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.1">
-    <title>Building with libsoup</title>
-    <sect3>
-      <title>Buildsystem Integration</title>
-    <para>Like other GNOME libraries, <application>libsoup</application> uses
-            <application>pkg-config</application> to provide compiler options. The package name is
-            "<literal>libsoup-3.0</literal>". </para>
-    <para>For example if you use Autotools:<informalexample>
-    <programlisting>PKG_CHECK_MODULES(LIBSOUP, [libsoup-3.0])
-AC_SUBST(LIBSOUP_CFLAGS)
-AC_SUBST(LIBSOUP_LIBS)</programlisting>
-        </informalexample></para>
-    <para>If you use Meson: <informalexample>
-            <programlisting>libsoup_dep = dependency('libsoup-3.0')</programlisting>
-        </informalexample></para>
-    </sect3>
-
-    <sect3>
-      <title>API Availability and Deprecation Warnings</title>
-<para>
-If you want to restrict your program to a particular
-<application>libsoup</application> version or range of versions, you
-can define <link
-linkend="SOUP-VERSION-MIN-REQUIRED:CAPS"><literal>SOUP_VERSION_MIN_REQUIRED</literal></link>
-and/or <link
-linkend="SOUP-VERSION-MAX-ALLOWED:CAPS"><literal>SOUP_VERSION_MAX_ALLOWED</literal></link>.
-For example with Autotools:
-</para>
-
-<informalexample><programlisting>LIBSOUP_CFLAGS="$LIBSOUP_CFLAGS -DSOUP_VERSION_MIN_REQUIRED=SOUP_VERSION_3_0"
-LIBSOUP_CFLAGS="$LIBSOUP_CFLAGS -DSOUP_VERSION_MAX_ALLOWED=SOUP_VERSION_3_2"</programlisting></informalexample>
-
-  <para>Or with Meson:</para>
-
-  <informalexample><programlisting>add_project_arguments(
-  '-DSOUP_VERSION_MIN_REQUIRED=SOUP_VERSION_2_99',
-  '-DSOUP_VERSION_MAX_ALLOWED=SOUP_VERSION_3_0',
-  language: 'c'
-)</programlisting></informalexample>
-  
-<para>The <literal>SOUP_VERSION_MIN_REQUIRED</literal> declaration states that the code is not
-        expected to compile on versions of <application>libsoup</application> older than the
-        indicated version, and so the compiler should print warnings if the code uses
-        functions that were deprecated as of that release.</para>
-
-<para>The <literal>SOUP_VERSION_MAX_ALLOWED</literal> declaration states that the code
-            <emphasis>is</emphasis> expected to compile on versions of
-            <application>libsoup</application> up to the indicated version, and so, when
-        compiling the program against a newer version than that, the compiler should print warnings
-        if the code uses functions that did not yet exist in the max-allowed release.</para>
-
-<para>You can use <link linkend="SOUP-CHECK-VERSION:CAPS"><literal>SOUP_CHECK_VERSION</literal></link> to check the version of libsoup at compile
-        time, to compile different code for different <application>libsoup</application> versions.
-        (If you are setting <literal>SOUP_VERSION_MIN_REQUIRED</literal> and
-            <literal>SOUP_VERSION_MAX_ALLOWED</literal> to different versions, as in the example
-        above, then you almost certainly need to be doing this.)</para>
-  </sect3>
-  <sect3>
-    <title>Headers</title>
-
-    <para>Code using <application>libsoup</application> should include the header like so:</para>
-<informalexample><programlisting>
-#include &lt;libsoup/soup.h&gt;
-</programlisting></informalexample>
-  </sect3>
-</sect1>
diff --git a/docs/reference/client-advanced.md b/docs/reference/client-advanced.md
new file mode 100644
index 00000000..e7bc1045
--- /dev/null
+++ b/docs/reference/client-advanced.md
@@ -0,0 +1,156 @@
+Title: Advances Usage
+Slug: client-advanced
+
+# Advanced Usage
+
+## Customizing Session Options
+
+When you create the session with [ctor@Session.new_with_options], you can
+specify various additional options. See the [class@Session] documentation for
+more details but these may be interesting: [property@Session:max-conns] and
+[property@Session:max-conns-per-host], [property@Session:user-agent],
+[property@Session:timeout], [property@Session:accept-language] and
+[property@Session:accept-language-auto].
+
+## Adding Session Features
+
+Additional session functionality is provided as [iface@SessionFeature]s, which
+can be added to or removed from a session.
+
+One such feature is [class@ContentDecoder] which is added by default. This
+advertises to servers that the client supports compression, and automatically
+decompresses compressed responses.
+
+Some other available features that you can add include:
+
+<table>
+    <tr>
+        <td>[class@Logger]</td>
+        <td>
+        A debugging aid, which logs all of libsoup's HTTP traffic
+        to <code>stdout</code> (or another place you specify).
+        </td>
+    </tr>
+    <tr>
+    <td>
+        [class@CookieJar], [class@CookieJarText],
+        and [class@CookieJarDB].
+    </td>
+    <td>
+        Support for HTTP cookies. [class@CookieJar]
+        provides non-persistent cookie storage, while
+        [class@CookieJarText] uses a text file to keep
+        track of cookies between sessions, and
+        [class@CookieJarDB] uses a
+        <tt>SQLite</tt> database.
+    </td>
+    </tr>
+    <tr>
+    <td>[class@ContentSniffer]</td>
+    <td>
+        Uses the HTML5 sniffing rules to attempt to
+        determine the Content-Type of a response when the
+        server does not identify the Content-Type, or appears to
+        have provided an incorrect one. 
+    </td>
+    </tr>
+</table>
+
+Use the [method@Session.add_feature_by_type] function to add features that don't
+require any configuration (such as [class@ContentSniffer]), and the
+[method@Session.add_feature]function to add features that must be constructed
+first (such as [class@Logger]). For example, an application might do something
+like the following:
+
+```c
+session = soup_session_new ();
+soup_session_add_feature_by_type (session, SOUP_TYPE_CONTENT_SNIFFER);
+
+if (debug_level) {
+    SoupLogger *logger = soup_logger_new (debug_level);
+    soup_session_add_feature (session, SOUP_SESSION_FEATURE (logger));
+    g_object_unref (logger);
+}
+```
+
+You can also remove features by calling [method@Session.remove_feature] or
+[method@Session.remove_feature_by_type].
+    
+## Using a proxy
+
+By default libsoup tries to respect the default proxy (as best as
+[func@Gio.ProxyResolver.get_default] knows), however you can set a custom one or
+disable it outright using the [property@Session:proxy-resolver] property. For
+example:
+
+```c
+{
+    GProxyResolver *resolver = g_simple_proxy_resolver_new ("https://my-proxy-example.org", NULL);
+    SoupSession *session = soup_session_new_with_options ("proxy-resolver", resolver, NULL);
+    g_object_unref (resolver);
+}
+```
+
+## Using the SoupMessage API
+
+The [class@Message] type contains all the state for a request and response pair
+that you send and receive to a server. For many more complex tasks you will have
+to create one of these and send it with the [method@Session.send] function. For
+example this sends a request with the `HEAD` method:
+    
+```c
+{
+    SoupSession *session = soup_session_new ();
+    SoupMessage *msg = soup_message_new (SOUP_METHOD_HEAD, "https://example.org");
+
+    // This allows you to also customize the request headers:
+    SoupMessageHeaders *request_headers = soup_message_get_request_headers (msg);
+    soup_message_headers_replace (request_headers, "Foo", "Bar");
+
+    GInputStream *in_stream = soup_session_send (session, msg, NULL, NULL);
+    if (in_stream) {
+        g_print ("Message was sent and recived a response of %u (%s)\n",
+                 soup_message_get_status (msg), soup_message_get_reason_phrase (msg));
+        // You can also inspect the response headers via soup_message_get_response_headers();
+        g_object_unref (in_stream);
+    }
+
+    g_object_unref (msg);
+    g_object_unref (session);
+}
+```
+
+## Handling authentication
+
+```c
+static gboolean
+authenticate_callback (SoupMessage *msg, SoupAuth *auth, gboolean retrying, gpointer user_data)
+{
+    if (retrying) {
+        // Maybe don't try again if our password failed
+        return FALSE;
+    }
+
+    soup_auth_authenticate (auth, "username", "password");
+
+    // Returning TRUE means we have or *will* handle it.
+    // soup_auth_authenticate() or soup_auth_cancel() can be called later
+    // for example after showing a prompt to the user or loading the password
+    // from a keyring.
+    return TRUE;
+}
+
+int main (int argc, char **argv)
+{
+    SoupSession *session = soup_session_new ();
+    SoupMessage *msg = soup_message_new (SOUP_METHOD_GET, "https://example.org");
+    g_signal_connect (msg, "authenticate", G_CALLBACK (authenticate_callback), NULL);
+    GInputStream *in_stream = soup_session_send (session, msg, NULL, NULL);
+
+    if (in_stream) {
+        g_object_unref (in_stream);
+    }
+
+    return 0;
+}
+```
diff --git a/docs/reference/client-advanced.xml b/docs/reference/client-advanced.xml
deleted file mode 100644
index c5ff3d4c..00000000
--- a/docs/reference/client-advanced.xml
+++ /dev/null
@@ -1,171 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="http://docbook.org/xml/5.1/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
-<?xml-model href="http://docbook.org/xml/5.1/sch/docbook.sch" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>
-<sect1 xmlns="http://docbook.org/ns/docbook" 
-    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.1">
-  <title>Advanced Usage</title>
-  <sect2>
-    <title>Customizing Session Options</title>
-    <para>When you create the session with <link linkend="soup-session-new-with-options"><function>soup_session_new_with_options()</function></link>,
-    you can specify various additional options. See the <link
-linkend="SoupSession"><type>SoupSession</type> documentation</link> for more details but these may be interesting:
-    <link linkend="SoupSession:max-conns"><literal>SoupSession:max-conns</literal></link> and <link linkend="SoupSession:max-conns-per-host"><literal>SoupSession:max-conns-per-host</literal></link>,
-    <link linkend="SoupSession:user-agent"><literal>SoupSession:user-agent</literal></link>, <link linkend="SoupSession:timeout"><literal>SoupSession:timeout</literal></link>,
-    <link linkend="SoupSession:accept-language"><literal>SoupSession:accept-language</literal></link> and <link linkend="SoupSession:accept-language-auto"><literal>SoupSession:accept-language-auto</literal></link></para>
-  </sect2>
-  <sect2>
-    <title>Adding Session Features</title>
-	<para>Additional session functionality is provided as <link
-linkend="SoupSessionFeature"><type>SoupSessionFeature</type></link>s,
-which can be added to or removed from a session.</para>
-
-	<para>One such feature is <link linkend="SoupContentDecoder"><type>SoupContentDecoder</type></link>
-    which is added by default. This advertises to servers that the
-client supports compression, and automatically decompresses compressed
-responses.
-</para>
-<para>
-Some other available features that you can add include:
-</para>
-
-<variablelist>
-    <varlistentry>
-	<term><link linkend="SoupLogger"><type>SoupLogger</type></link></term>
-	<listitem><para>
-	    A debugging aid, which logs all of libsoup's HTTP traffic
-	    to <literal>stdout</literal> (or another place you specify).
-	</para></listitem>
-    </varlistentry>
-    <varlistentry>
-	<term>
-	    <link linkend="SoupCookieJar"><type>SoupCookieJar</type></link>,
-	    <link linkend="SoupCookieJarText"><type>SoupCookieJarText</type></link>,
-	    and <link linkend="SoupCookieJarDB"><type>SoupCookieJarDB</type></link>
-	</term>
-	<listitem><para>
-	    Support for HTTP cookies. <type>SoupCookieJar</type>
-	    provides non-persistent cookie storage, while
-	    <type>SoupCookieJarText</type> uses a text file to keep
-	    track of cookies between sessions, and
-	    <type>SoupCookieJarDB</type> uses a
-	    <application>SQLite</application> database.
-	</para></listitem>
-    </varlistentry>
-    <varlistentry>
-	<term><link linkend="SoupContentSniffer"><type>SoupContentSniffer</type></link></term>
-	<listitem><para>
-	    Uses the HTML5 sniffing rules to attempt to
-	    determine the Content-Type of a response when the
-	    server does not identify the Content-Type, or appears to
-	    have provided an incorrect one. 
-	</para></listitem>
-    </varlistentry>
-</variablelist>
-
-<para>
-Use the <link
-linkend="soup-session-add-feature-by-type"><function>soup_session_add_feature_by_type()</function></link> function to
-add features that don't require any configuration (such as <link
-linkend="SoupContentSniffer"><type>SoupContentSniffer</type></link>),
-and the <link
-linkend="soup-session-add-feature"><function>soup_session_add_feature()</function></link>function to add features that must be
-constructed first (such as <link
-linkend="SoupLogger"><type>SoupLogger</type></link>). For example, an
-application might do something like the following:
-</para>
-
-<informalexample><programlisting><![CDATA[session = soup_session_new ();
-soup_session_add_feature_by_type (session, SOUP_TYPE_CONTENT_SNIFFER);
-
-if (debug_level) {
-    SoupLogger *logger = soup_logger_new (debug_level);
-    soup_session_add_feature (session, SOUP_SESSION_FEATURE (logger));
-    g_object_unref (logger);
-}]]></programlisting></informalexample>
-
-    <para>You can also remove features by calling <link
-linkend="soup-session-remove-feature"><function>soup_session_remove_feature()</function></link> or
-<link
-linkend="soup-session-remove-feature-by-type"><function>soup_session_remove_feature_by_type()</function></link></para>.
-
-    <para>See the <link linkend="additional-features">Additional Features</link> section for other features.
-    </para>
-  </sect2>
-  <sect2>
-    <title>Using a proxy</title>
-    <para>By default libsoup tries to respect the default proxy (as best as <link
-linkend="g-proxy-resolver-get-default"><function>g_proxy_resolver_get_default()</function></link> knows), however you can set
-    a custom one or disable it outright using the <link linkend="SoupSession:proxy-resolver"><literal>SoupSession:proxy-resolver</literal></link>
-    property. For example:</para>
-<informalexample><programlisting><![CDATA[
-{
-    GProxyResolver *resolver = g_simple_proxy_resolver_new ("https://my-proxy-example.org", NULL);
-    SoupSession *session = soup_session_new_with_options ("proxy-resolver", resolver, NULL);
-    g_object_unref (resolver);
-}]]>
-</programlisting></informalexample>
-  </sect2>
-  <sect2>
-    <title>Using the SoupMessage API</title>
-    <para>The <type>SoupMessage</type> type contains all the state for a request and response pair that you send and recieve
-    to a server. For many more complex tasks you will have to create one of these and send it with the <function>soup_session_send()</function>
-    function. For example this sends a request with the <literal>HEAD</literal> method:
-    </para>
-<informalexample><programlisting><![CDATA[
-{
-    SoupSession *session = soup_session_new ();
-    SoupMessage *msg = soup_message_new (SOUP_METHOD_HEAD, "https://example.org");
-
-    // This allows you to also customize the request headers:
-    SoupMessageHeaders *request_headers = soup_message_get_request_headers (msg);
-    soup_message_headers_replace (request_headers, "Foo", "Bar");
-
-    GInputStream *in_stream = soup_session_send (session, msg, NULL, NULL);
-    if (in_stream) {
-        g_print ("Message was sent and recived a response of %u (%s)\n",
-                 soup_message_get_status (msg), soup_message_get_reason_phrase (msg));
-        // You can also inspect the response headers via soup_message_get_response_headers();
-        g_object_unref (in_stream);
-    }
-
-    g_object_unref (msg);
-    g_object_unref (session);
-}]]>
-</programlisting></informalexample>
-  </sect2>
-  <sect2>
-    <title>Handling authentication</title>
-<informalexample><programlisting><![CDATA[
-static gboolean
-authenticate_callback (SoupMessage *msg, SoupAuth *auth, gboolean retrying, gpointer user_data)
-{
-    if (retrying) {
-        // Maybe don't try again if our password failed
-        return FALSE;
-    }
-
-    soup_auth_authenticate (auth, "username", "password");
-
-    // Returning TRUE means we have or *will* handle it.
-    // soup_auth_authenticate() or soup_auth_cancel() can be called later
-    // for example after showing a prompt to the user or loading the password
-    // from a keyring.
-    return TRUE;
-}
-
-int main (int argc, char **argv)
-{
-    SoupSession *session = soup_session_new ();
-    SoupMessage *msg = soup_message_new (SOUP_METHOD_GET, "https://example.org");
-    g_signal_connect (msg, "authenticate", G_CALLBACK (authenticate_callback), NULL);
-    GInputStream *in_stream = soup_session_send (session, msg, NULL, NULL);
-
-    if (in_stream) {
-        g_object_unref (in_stream);
-    }
-
-    return 0;
-}]]>
-</programlisting></informalexample>
-  </sect2>
-</sect1>
\ No newline at end of file
diff --git a/docs/reference/client-basic.xml b/docs/reference/client-basic.md
index 00b6baa4..a1909f27 100644
--- a/docs/reference/client-basic.xml
+++ b/docs/reference/client-basic.md
@@ -1,25 +1,25 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="http://docbook.org/xml/5.1/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
-<?xml-model href="http://docbook.org/xml/5.1/sch/docbook.sch" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>
-<sect1 xmlns="http://docbook.org/ns/docbook" 
-    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.1">
-    <title>Creating a Basic Client</title>
-    <para>libsoup provides a feature rich and complete HTTP client feature-set however in this guide
-        we will just be touching the basics. See … for a more in-depth example.</para>
-        <sect2>
-            <title>Creating a SoupSession</title>
-            <para>The core of libsoup is <type>SoupSession</type>; It contains all of the state of a
-                client including managing connections, queuing messages, handling authentication and
-                redirects, and much more. For now lets assume the default set of options and
-                features it provides are acceptable for most usage in which case you simply need to
-                create one with <link linkend="soup-session-new"><function>soup_session_new()</function></link>.</para>
-        </sect2>
-        <sect2>
-            <title>Downloading Into Memory</title>
-            <para>A common use case is that you simply want to request an HTTP resource and store it
-                for later use. There are a few methods of doing this but libsoup provides a high
-                level API to accomplish this:</para>
-<informalexample><programlisting><![CDATA[#include <libsoup/soup.h>
+Title: Creating a Basic Client
+Slug: client-basic
+
+# Creating a Basic Client
+
+libsoup provides a feature rich and complete HTTP client feature-set however in this guide we will just be touching the basics.
+
+## Creating a SoupSession
+The core of libsoup is [class@Session]; It contains all of the state of a client
+including managing connections, queuing messages, handling authentication and
+redirects, and much more. For now lets assume the default set of options and
+features it provides are acceptable for most usage in which case you simply need
+to create one with [ctor@Session.new].
+
+## Downloading Into Memory
+
+A common use case is that you simply want to request an HTTP resource and store
+it for later use. There are a few methods of doing this but libsoup provides a high
+level API to accomplish this:
+
+```c
+#include <libsoup/soup.h>
 
 int main (int argc, char **argv)
 {
@@ -54,16 +54,17 @@ int main (int argc, char **argv)
     g_object_unref (msg);
     g_object_unref (session);
     return 0;
-}]]>
-</programlisting></informalexample>
-        </sect2>
-        <sect2>
-            <title>Efficiently Streaming Data</title>
-            <para>While sometimes you want to store an entire download in memory it is often more
-                efficient to stream the data in chunks. In this example we will write the output to
-                a file.</para>
-            <para>
-<informalexample><programlisting><![CDATA[#include <libsoup/soup.h>
+}
+```
+
+## Efficiently Streaming Data
+
+While sometimes you want to store an entire download in memory it is often more
+efficient to stream the data in chunks. In this example we will write the output
+to a file.
+            
+```c
+#include <libsoup/soup.h>
 
 int main (int argc, char **argv)
 {
@@ -128,18 +129,19 @@ int main (int argc, char **argv)
     g_object_unref (msg);
     g_object_unref (session);
     return error ? 1 : 0;
-}]]>
-</programlisting></informalexample>
-            </para>
-        </sect2>
-        <sect2>
-            <title>Using Asynchronously</title>
-            <para>If you are using libsoup in an application with a <link linkend="GMainLoop"><type>GMainLoop</type></link> such as a GTK application
-            you do not want to block the mainloop by doing IO. To accomplish this libsoup provides an
-            asynchronous version of each of the APIs: <link linkend="soup-session-send-and-read-async"><function>soup_session_send_and_read_async()</function></link>
-            and <link linkend="soup-session-send-async"><function>soup_session_send_async()</function></link>. These behave the same as all async GLib
-            APIs, for example:</para>
-<informalexample><programlisting><![CDATA[#include <libsoup/soup.h>
+}
+```
+
+## Using Asynchronously
+
+If you are using libsoup in an application with a [struct@GLib.MainLoop] such as
+a GTK application you do not want to block the mainloop by doing IO. To
+accomplish this libsoup provides an asynchronous version of each of the APIs:
+[method@Session.send_and_read_async] and [method@Session.send_async]. These
+behave the same as all async GLib APIs, for example:
+
+```c
+#include <libsoup/soup.h>
 
 static void on_load_callback (GObject *source, GAsyncResult *result, gpointer user_data)
 {
@@ -177,7 +179,5 @@ int main (int argc, char **argv)
     g_object_unref (msg);
     g_object_unref (session);
     return 0;
-}]]>
-</programlisting></informalexample>
-        </sect2>
-</sect1>
+}
+```
diff --git a/docs/reference/client-howto.xml b/docs/reference/client-howto.xml
deleted file mode 100644
index 898cfaf1..00000000
--- a/docs/reference/client-howto.xml
+++ /dev/null
@@ -1,535 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
-               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
-<refentry id="libsoup-client-howto">
-<refmeta>
-<refentrytitle>libsoup Client Basics</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>LIBSOUP Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>libsoup Client Basics</refname><refpurpose>Client-side tutorial</refpurpose>
-</refnamediv>
-
-<refsect2>
-<para>
-This section explains how to use <application>libsoup</application> as
-an HTTP client using several new APIs introduced in version 2.42. If
-you want to be compatible with older versions of
-<application>libsoup</application>, consult the documentation for that
-version.
-</para>
-</refsect2>
-
-<refsect2>
-<title>Creating a <type>SoupSession</type></title>
-
-<para>
-The first step in using the client API is to create a <link
-linkend="SoupSession"><type>SoupSession</type></link>. The session object
-encapsulates all of the state that <application>libsoup</application>
-is keeping on behalf of your program; cached HTTP connections,
-authentication information, etc.
-</para>
-
-<para>
-When you create the session with <link
-linkend="soup-session-new-with-options"><function>soup_session_new_with_options</function></link>,
-you can specify various additional options:
-</para>
-
-<variablelist>
-    <varlistentry>
-	<term><link linkend="SoupSession:max-conns"><literal>"max-conns"</literal></link></term>
-	<listitem><para>
-	    Allows you to set the maximum total number of connections
-	    the session will have open at one time. (Once it reaches
-	    this limit, it will either close idle connections, or
-	    wait for existing connections to free up before starting
-	    new requests.) The default value is 10.
-	</para></listitem>
-    </varlistentry>
-    <varlistentry>
-	<term><link linkend="SoupSession:max-conns-per-host"><literal>"max-conns-per-host"</literal></link></term>
-	<listitem><para>
-	    Allows you to set the maximum total number of connections
-	    the session will have open <emphasis>to a single
-	    host</emphasis> at one time. The default value is 2.
-	</para></listitem>
-    </varlistentry>
-    <varlistentry>
-	<term><link linkend="SoupSession:user-agent"><literal>"user-agent"</literal></link></term>
-	<listitem><para>
-	    Allows you to set a User-Agent string that will be sent
-	    on all outgoing requests.
-	</para></listitem>
-    </varlistentry>
-    <varlistentry>
-	<term><link linkend="SoupSession:accept-language"><literal>"accept-language"</literal></link>
-	and <link linkend="SoupSession:accept-language-auto"><literal>"accept-language-auto"</literal></link></term>
-	<listitem><para>
-	    Allow you to set an Accept-Language header on all outgoing
-	    requests. <literal>"accept-language"</literal>
-	    takes a list of language tags to use, while
-	    <literal>"accept-language-auto"</literal>
-	    automatically generates the list from the user's locale
-	    settings.
-	</para></listitem>
-    </varlistentry>
-    <varlistentry>
-	<term><link linkend="SoupSession:proxy-resolver"><literal>"proxy-resolver"</literal></link></term>
-	<listitem>
-	    <para>
-		<link linkend="SoupSession:proxy-resolver"><literal>"proxy-resolver"</literal></link>
-		specifies a <link
-		linkend="GProxyResolver"><type>GProxyResolver</type></link>
-		to use to determine the HTTP proxies to use. By default,
-		this is set to the resolver returned by <link
-		linkend="g-proxy-resolver-get-default"><function>g_proxy_resolver_get_default</function></link>,
-		so you do not need to set it yourself.
-	    </para>
-	</listitem>
-    </varlistentry>
-    <varlistentry>
-	<term><link linkend="SoupSession:add-feature"><literal>"add-feature"</literal></link> and <link linkend="SOUP-SESSION-ADD-FEATURE-BY-TYPE:CAPS"><literal>"add-feature-by-type"</literal></link></term>
-	<listitem><para>
-	    These allow you to specify <link
-	    linkend="SoupSessionFeature"><type>SoupSessionFeature</type></link>s
-	    (discussed <link linkend="session-features">below</link>)
-	    to add at construct-time.
-	</para></listitem>
-    </varlistentry>
-</variablelist>
-
-<para>
-Other properties are also available; see the <link
-linkend="SoupSession"><type>SoupSession</type></link> documentation for
-more details.
-</para>
-
-<para>
-If you don't need to specify any options, you can just use <link
-linkend="soup-session-new"><function>soup_session_new</function></link>,
-which takes no arguments.
-</para>
-
-</refsect2>
-
-<refsect2 id="session-features">
-<title>Session features</title>
-
-<para>
-Additional session functionality is provided as <link
-linkend="SoupSessionFeature"><type>SoupSessionFeature</type></link>s,
-which can be added to a session, via the <link
-linkend="SoupSession:add-feature"><literal>"add-feature"</literal></link>
-and <link
-linkend="SoupSession:add-feature-by-type"><literal>"add-feature-by-type"</literal></link>
-options at session-construction-time, or afterward via the <link
-linkend="soup-session-add-feature"><function>soup_session_add_feature</function></link>
-and <link
-linkend="soup-session-add-feature-by-type"><function>soup_session_add_feature_by_type</function></link>
-functions.
-</para>
-
-<para>
-A <link
-linkend="SoupContentDecoder"><type>SoupContentDecoder</type></link> is
-added for you automatically. This advertises to servers that the
-client supports compression, and automatically decompresses compressed
-responses.
-</para>
-
-<para>
-Some other available features that you can add include:
-</para>
-
-<variablelist>
-    <varlistentry>
-	<term><link linkend="SoupLogger"><type>SoupLogger</type></link></term>
-	<listitem><para>
-	    A debugging aid, which logs all of libsoup's HTTP traffic
-	    to <literal>stdout</literal> (or another place you specify).
-	</para></listitem>
-    </varlistentry>
-    <varlistentry>
-	<term>
-	    <link linkend="SoupCookieJar"><type>SoupCookieJar</type></link>,
-	    <link linkend="SoupCookieJarText"><type>SoupCookieJarText</type></link>,
-	    and <link linkend="SoupCookieJarDB"><type>SoupCookieJarDB</type></link>
-	</term>
-	<listitem><para>
-	    Support for HTTP cookies. <type>SoupCookieJar</type>
-	    provides non-persistent cookie storage, while
-	    <type>SoupCookieJarText</type> uses a text file to keep
-	    track of cookies between sessions, and
-	    <type>SoupCookieJarDB</type> uses a
-	    <application>SQLite</application> database.
-	</para></listitem>
-    </varlistentry>
-    <varlistentry>
-	<term><link linkend="SoupContentSniffer"><type>SoupContentSniffer</type></link></term>
-	<listitem><para>
-	    Uses the HTML5 sniffing rules to attempt to
-	    determine the Content-Type of a response when the
-	    server does not identify the Content-Type, or appears to
-	    have provided an incorrect one. 
-	</para></listitem>
-    </varlistentry>
-</variablelist>
-
-<para>
-Use the "add_feature_by_type" property/function to add features that
-don't require any configuration (such as <link
-linkend="SoupContentSniffer"><type>SoupContentSniffer</type></link>),
-and the "add_feature" property/function to add features that must be
-constructed first (such as <link
-linkend="SoupLogger"><type>SoupLogger</type></link>). For example, an
-application might do something like the following:
-</para>
-
-<informalexample><programlisting>
-	session = soup_session_new_with_options (
-		"add-feature-by-type", SOUP_TYPE_CONTENT_SNIFFER,
-		NULL);
-
-	if (debug_level) {
-		SoupLogger *logger;
-
-		logger = soup_logger_new (debug_level, -1);
-		soup_session_add_feature (session, SOUP_SESSION_FEATURE (logger));
-		g_object_unref (logger);
-	}
-</programlisting></informalexample>
-
-</refsect2>
-
-<refsect2>
-<title>Creating and Sending SoupMessages</title>
-
-<para>
-Once you have a session, you send HTTP requests using <link
-linkend="SoupMessage"><type>SoupMessage</type></link>. In the simplest
-case, you only need to create the message and it's ready to send:
-</para>
-
-<informalexample><programlisting>
-	SoupMessage *msg;
-
-	msg = soup_message_new ("GET", "http://example.com/");
-</programlisting></informalexample>
-
-<para>
-In more complicated cases, you can use various <link
-linkend="SoupMessage">SoupMessage</link>, <link
-linkend="SoupMessageHeaders">SoupMessageHeaders</link>, and <link
-linkend="SoupMessageBody">SoupMessageBody</link> methods to set the
-request headers and body of the message:
-</para>
-
-<informalexample><programlisting>
-	SoupMessage *msg;
-
-	msg = soup_message_new ("POST", "http://example.com/form.cgi");
-	soup_message_set_request (msg, "application/x-www-form-urlencoded",
-	                          SOUP_MEMORY_COPY, formdata, strlen (formdata));
-	soup_message_headers_append (msg->request_headers, "Referer", referring_url);
-</programlisting></informalexample>
-
-<para>
-(Although this is a bad example, because
-<application>libsoup</application> actually has convenience methods
-for dealing with <link linkend="libsoup-3.0-HTML-Form-Support">HTML
-forms</link>.)
-</para>
-
-<para>
-You can also use <link
-linkend="soup-message-set-flags"><function>soup_message_set_flags</function></link>
-to change some default behaviors. For example, by default,
-<type>SoupSession</type> automatically handles responses from the
-server that redirect to another URL. If you would like to handle these
-yourself, you can set the <link linkend="SOUP-MESSAGE-NO-REDIRECT:CAPS"><literal>SOUP_MESSAGE_NO_REDIRECT</literal></link>
-flag.
-</para>
-
-<refsect3>
-<title>Sending a Message Synchronously</title>
-
-<para>
-To send a message and wait for the response, use <link
-linkend="soup-session-send"><function>soup_session_send</function></link>:
-</para>
-
-<informalexample><programlisting>
-	GInputStream *stream;
-	GError *error = NULL;
-
-	stream = soup_session_send (session, msg, cancellable, &amp;error);
-</programlisting></informalexample>
-
-<para>
-At the point when <function>soup_session_send</function> returns, the
-request will have been sent, and the response headers read back in;
-you can examine the message's <structfield>status_code</structfield>,
-<structfield>reason_phrase</structfield>, and
-<structfield>response_headers</structfield> fields to see the response
-metadata. To get the response body, read from the returned <link
-linkend="GInputStream"><type>GInputStream</type></link>, and close it
-when you are done.
-</para>
-
-<para>
-Note that <function>soup_session_send</function> only returns an error
-if a transport-level problem occurs (eg, it could not connect to the
-host, or the request was cancelled). Use the message's
-<structfield>status_code</structfield> field to determine whether the
-request was successful or not at the HTTP level (ie, "<literal>200
-OK</literal>" vs "<literal>401 Bad Request</literal>").
-</para>
-
-<para>
-If you would prefer to have <application>libsoup</application> gather
-the response body for you and then return it all at once, you can use
-the older
-<link linkend="soup-session-send-message"><function>soup_session_send_message</function></link>
-API:
-</para>
-
-<informalexample><programlisting>
-	guint status;
-
-	status = soup_session_send_message (session, msg);
-</programlisting></informalexample>
-
-<para>
-In this case, the response body will be available in the message's
-<structfield>response_body</structfield> field, and transport-level
-errors will be indicated in the <structfield>status_code</structfield>
-field via special pseudo-HTTP-status codes like <link
-linkend="SOUP-STATUS-CANT-CONNECT:CAPS"><literal>SOUP_STATUS_CANT_CONNECT</literal></link>.
-</para>
-
-</refsect3>
-
-<refsect3>
-<title>Sending a Message Asynchronously</title>
-
-<para>
-To send a message asynchronously, use <link
-linkend="soup-session-send-async"><function>soup_session_send_async</function></link>:
-</para>
-
-<informalexample><programlisting>
-{
-	...
-	soup_session_send_async (session, msg, cancellable, my_callback, my_callback_data);
-	...
-}
-
-static void
-my_callback (GObject *object, GAsyncResult *result, gpointer user_data)
-{
-	GInputStream *stream;
-	GError *error = NULL;
-
-	stream = soup_session_send_finish (SOUP_SESSION (object), result, &amp;error);
-	...
-}
-</programlisting></informalexample>
-
-<para>
-The message will be added to the session's queue, and eventually (when
-control is returned back to the main loop), it will be sent and the
-response will be read. When the message has been sent, and its
-headers received, the callback will be invoked, in the standard
-<link linkend="GAsyncReadyCallback"><type>GAsyncReadyCallback</type></link>
-style.
-</para>
-
-<para>
-As with synchronous sending, there is also an alternate API, <link
-linkend="soup-session-queue-message"><function>soup_session_queue_message</function></link>,
-in which your callback is not invoked until the response has been
-completely read:
-</para>
-
-<informalexample><programlisting>
-{
-	...
-	soup_session_queue_message (session, msg, my_callback, my_callback_data);
-	...
-}
-
-static void
-my_callback (SoupSession *session, SoupMessage *msg, gpointer user_data)
-{
-	/* msg->response_body contains the response */
-}
-</programlisting></informalexample>
-
-<para>
-<link
-linkend="soup-session-queue-message"><function>soup_session_queue_message</function></link>
-is slightly unusual in that it steals a reference to the message
-object, and unrefs it after the last callback is invoked on it. So
-when using this API, you should not unref the message yourself.
-</para>
-
-</refsect3>
-
-</refsect2>
-
-<refsect2>
-<title>Processing the Response</title>
-
-<para>
-Once you have received the initial response from the server,
-synchronously or asynchronously, streaming or not, you can look at the
-response fields in the <literal>SoupMessage</literal> to decide what
-to do next. The <structfield>status_code</structfield> and
-<structfield>reason_phrase</structfield> fields contain the numeric
-status and textual status response from the server.
-<structfield>response_headers</structfield> contains the response
-headers, which you can investigate using <link
-linkend="soup-message-headers-get-list"><function>soup_message_headers_get_list</function></link>
-and <link
-linkend="soup-message-headers-foreach"><function>soup_message_headers_foreach</function></link>.
-</para>
-
-<para>
-<link
-linkend="SoupMessageHeaders"><type>SoupMessageHeaders</type></link>
-automatically parses several important headers in
-<structfield>response_headers</structfield> for you and provides
-specialized accessors for them. Eg, <link
-linkend="soup-message-headers-get-content-type"><function>soup_message_headers_get_content_type</function></link>.
-There are several generic methods such as <link
-linkend="soup-header-parse-param-list"><function>soup_header_parse_param_list</function></link>
-(for parsing an attribute-list-type header) and <link
-linkend="soup-header-contains"><function>soup_header_contains</function></link>
-(for quickly testing if a list-type header contains a particular
-token). These handle the various syntactical oddities of parsing HTTP
-headers much better than functions like
-<function>g_strsplit</function> or <function>strstr</function>.
-</para>
-
-</refsect2>
-
-<refsect2>
-<title>Handling Authentication</title>
-
-<para>
-<type>SoupSession</type> handles most of the details of HTTP
-authentication for you. If it receives a 401 ("Unauthorized") or 407
-("Proxy Authentication Required") response, the session will emit the
-<link linkend="SoupSession-authenticate">authenticate</link> signal,
-providing you with a <link
-linkend="SoupAuth"><type>SoupAuth</type></link> object indicating the
-authentication type ("Basic", "Digest", or "NTLM") and the realm name
-provided by the server. If you have a username and password available
-(or can generate one), call <link
-linkend="soup-auth-authenticate"><function>soup_auth_authenticate</function></link>
-to give the information to libsoup. The session will automatically
-requeue the message and try it again with that authentication
-information. (If you don't call
-<function>soup_auth_authenticate</function>, the session will just
-return the message to the application with its 401 or 407 status.)
-</para>
-
-<para>
-If the server doesn't accept the username and password provided, the
-session will emit <link
-linkend="SoupSession-authenticate">authenticate</link> again, with the
-<literal>retrying</literal> parameter set to <literal>TRUE</literal>. This lets the
-application know that the information it provided earlier was
-incorrect, and gives it a chance to try again. If this
-username/password pair also doesn't work, the session will contine to
-emit <literal>authenticate</literal> again and again until the
-provided username/password successfully authenticates, or until the
-signal handler fails to call <link
-linkend="soup-auth-authenticate"><function>soup_auth_authenticate</function></link>,
-at which point <application>libsoup</application> will allow the
-message to fail (with status 401 or 407).
-</para>
-
-<para>
-If you need to handle authentication asynchronously (eg, to pop up a
-password dialog without recursively entering the main loop), you can
-do that as well. Just call <link
-linkend="soup-session-pause-message"><function>soup_session_pause_message</function></link>
-on the message before returning from the signal handler, and
-<function>g_object_ref</function> the <type>SoupAuth</type>. Then,
-later on, after calling <function>soup_auth_authenticate</function>
-(or deciding not to), call <link
-linkend="soup-session-unpause-message"><function>soup_session_unpause_message</function></link>
-to resume the paused message.
-</para>
-
-<para>
-By default, NTLM authentication is not enabled. To add NTLM support to
-a session, call:
-</para>
-
-<informalexample><programlisting>
-	soup_session_add_feature_by_type (session, SOUP_TYPE_AUTH_NTLM);
-</programlisting></informalexample>
-
-<para>
-(You can also disable Basic or Digest authentication by calling <link
-linkend="soup-session-remove-feature-by-type"><function>soup_session_remove_feature_by_type</function></link>
-on <link linkend="SOUP-TYPE-AUTH-BASIC:CAPS"><literal>SOUP_TYPE_AUTH_BASIC</literal></link>
-or <link linkend="SOUP-TYPE-AUTH-DIGEST:CAPS"><literal>SOUP_TYPE_AUTH_DIGEST</literal></link>.)
-</para>
-
-</refsect2>
-
-<refsect2>
-<title>Multi-threaded usage</title>
-
-<para>
-A <link linkend="SoupSession"><type>SoupSession</type></link> can be
-used from multiple threads. However, if you are using the async APIs,
-then each thread you use the session from must have its own
-thread-default <link linkend="GMainContext"><type>GMainContext</type></link>.
-</para>
-
-<para>
-<link linkend="SoupMessage"><type>SoupMessage</type></link> is
-<emphasis>not</emphasis> thread-safe, so once you send a message on
-the session, you must not interact with it from any thread other than
-the one where it was sent.
-</para>
-
-</refsect2>
-
-<refsect2>
-<title>Sample Programs</title>
-
-<para>
-A few sample programs are available in the
-<application>libsoup</application> sources, in the
-<literal>examples</literal> directory:
-</para>
-
-<itemizedlist>
-    <listitem><para>
-	<emphasis role="bold"><literal>get</literal></emphasis> is a simple command-line
-	HTTP GET utility using the asynchronous API.
-    </para></listitem>
-
-    <listitem><para>
-	<emphasis role="bold"><literal>simple-proxy</literal></emphasis> uses both the
-	client and server APIs to create a simple (and not very
-	RFC-compliant) proxy server.
-    </para></listitem>
-</itemizedlist>
-
-<para>
-More complicated examples are available in GNOME git.
-</para>
-
-</refsect2>
-
-</refentry>
diff --git a/docs/reference/client-tls.xml b/docs/reference/client-tls.md
index 2e329e65..e6e1974d 100644
--- a/docs/reference/client-tls.xml
+++ b/docs/reference/client-tls.md
@@ -1,15 +1,16 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="http://docbook.org/xml/5.1/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
-<?xml-model href="http://docbook.org/xml/5.1/sch/docbook.sch" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>
-<sect1 xmlns="http://docbook.org/ns/docbook" 
-    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.1">
-  <title>Everything TLS Related</title>
-  <para>libsoup comes with TLS support provided by glib-networking. This has multiple backends
-  including gnutls (default on all platforms), SChannel on Windows, or OpenSSL.</para>
-  <sect2>
-    <title>Accepting Invalid or Pinned Certificates</title>
-    <para>This makes use of the <literal>SoupMessage::accept-certificate</literal> signal.</para>
-<informalexample><programlisting><![CDATA[
+Title: Everything TLS Related
+Slug: client-tls
+
+# Everything TLS Related
+
+libsoup comes with TLS support provided by glib-networking. This has multiple backends
+including gnutls (default on all platforms), SChannel on Windows, or OpenSSL.
+
+## Accepting Invalid or Pinned Certificates
+
+This makes use of the [signal@Message::accept-certificate] signal.
+
+```c
 static gboolean
 accept_certificate_callback (SoupMessage *msg, GTlsCertificate *certificate,
                              GTlsCertificateFlags tls_errors, gpointer user_data)
@@ -32,12 +33,12 @@ int main (int argc, char **argv)
     }
 
     return 0;
-}]]>
-</programlisting></informalexample>
-  </sect2>
-  <sect2>
-    <title>Setting a Custom CA</title>
-<informalexample><programlisting><![CDATA[
+}
+```
+
+## Setting a Custom CA
+
+```c
 {
     GError *error = NULL;
     // NOTE: This is blocking IO
@@ -51,12 +52,12 @@ int main (int argc, char **argv)
 
     SoupSession *session = soup_session_new_with_options ("tls-database", tls_db, NULL);
     g_object_unref (tls_db);
-}]]>
-</programlisting></informalexample>
-  </sect2>
-  <sect2>
-    <title>Using Client Certificates</title>
-<informalexample><programlisting><![CDATA[
+}
+```
+
+## Using Client Certificates
+
+```c
 static gboolean
 on_request_certificate (SoupMessage *msg, GTlsClientConnection *conn, gpointer user_data)
 {
@@ -96,7 +97,5 @@ int main (int argc, char **argv)
     g_object_unref (session);
     g_object_unref (client_cert);
     return 0;
-}]]>
-</programlisting></informalexample>
-  </sect2>
-</sect1>
\ No newline at end of file
+}
+```
diff --git a/docs/reference/libsoup-3.0-docs.xml b/docs/reference/libsoup-3.0-docs.xml
deleted file mode 100644
index ae3845f2..00000000
--- a/docs/reference/libsoup-3.0-docs.xml
+++ /dev/null
@@ -1,118 +0,0 @@
-<?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">
-<book xmlns="http://docbook.org/ns/docbook" id="index"
-  xmlns:xi="http://www.w3.org/2003/XInclude">
-  <bookinfo>
-    <title>libsoup Reference Manual</title>
-    <releaseinfo>
-      This documentation is for libsoup 3.0.
-      You can find older versions online at <ulink role="online-location" url="https://libsoup.org/libsoup-2.4/index.html">https://libsoup.org/libsoup-2.4/</ulink>.
-    </releaseinfo>
-  </bookinfo>
-
-  <part>
-    <title>Overview</title>
-    <chapter>
-        <title>Tutorial</title>
-        <xi:include href="build-howto.xml"/>
-        <xi:include href="client-basic.xml"/>
-        <xi:include href="client-advanced.xml"/>
-        <xi:include href="client-tls.xml"/>
-        <xi:include href="server-howto.xml"/>
-    </chapter>
-
-    <xi:include href="migrating-from-libsoup-2.xml"/>
-  </part>
-
-  <part>
-    <title>API Reference</title>
-    <chapter>
-        <title>Core HTTP API</title>
-        <xi:include href="xml/soup-cookie.xml"/>
-        <xi:include href="xml/soup-message.xml"/>
-        <xi:include href="xml/soup-message-headers.xml"/>
-        <xi:include href="xml/soup-headers.xml"/>
-        <xi:include href="xml/soup-method.xml"/>
-        <xi:include href="xml/soup-multipart.xml"/>
-        <xi:include href="xml/soup-multipart-input-stream.xml"/>
-        <xi:include href="xml/soup-session.xml"/>
-        <xi:include href="xml/soup-status.xml"/>
-    </chapter>
-
-    <chapter>
-        <title>HTTP Server</title>
-        <xi:include href="xml/soup-server.xml"/>
-        <xi:include href="xml/soup-server-message.xml"/>
-        <xi:include href="xml/soup-message-body.xml"/>
-    </chapter>
-
-    <chapter id="additional-features">
-        <title>Additional Features</title>
-        <xi:include href="xml/soup-session-feature.xml"/>
-        <xi:include href="xml/soup-content-decoder.xml"/>
-        <xi:include href="xml/soup-content-sniffer.xml"/>
-        <xi:include href="xml/soup-logger.xml"/>
-        <section>
-        <title>Authentication</title>
-        <xi:include href="xml/soup-auth-manager.xml"/>
-        <xi:include href="xml/soup-auth.xml"/>
-        <xi:include href="xml/soup-auth-domain.xml"/>
-        <xi:include href="xml/soup-auth-domain-basic.xml"/>
-        <xi:include href="xml/soup-auth-domain-digest.xml"/>
-        </section>
-        <section>
-            <title>Caching</title>
-            <xi:include href="xml/soup-cache.xml"/>
-        </section>
-        <section>
-        <title>Cookie Storage Support</title>
-        <xi:include href="xml/soup-cookie-jar.xml"/>
-        <xi:include href="xml/soup-cookie-jar-text.xml"/>
-        <xi:include href="xml/soup-cookie-jar-db.xml"/>
-        </section>
-        <section>
-        <title>HSTS Support</title>
-        <xi:include href="xml/soup-hsts-enforcer.xml"/>
-        <xi:include href="xml/soup-hsts-enforcer-db.xml"/>
-        <xi:include href="xml/soup-hsts-policy.xml"/>
-        </section>
-        <section>
-        <title>Metrics</title>
-        <xi:include href="xml/soup-message-metrics.xml"/>
-        </section>
-    </chapter>
-
-    <chapter>
-        <title>Web Services APIs</title>
-        <xi:include href="xml/soup-form.xml"/>
-        <section>
-        <title>WebSocket Support</title>
-        <xi:include href="xml/soup-websocket.xml"/>
-        <xi:include href="xml/soup-websocket-extension.xml"/>
-        </section>
-    </chapter>
-
-    <chapter>
-        <title>Utility API</title>
-        <xi:include href="xml/soup-date-utils.xml"/>
-        <xi:include href="xml/soup-tld.xml"/>
-        <xi:include href="xml/soup-uri-utils.xml"/>
-        <xi:include href="xml/soup-version.xml"/>
-    </chapter>
-  </part>
-
-  <index id="api-index-full">
-    <title>Index of all symbols</title>
-    <xi:include href="xml/api-index-full.xml"></xi:include>
-  </index>
-  <index id="api-index-deprecated" role="deprecated">
-    <title>Index of deprecated symbols</title>
-    <xi:include href="xml/api-index-deprecated.xml"></xi:include>
-  </index>
-
-  <xi:include href="xml/annotation-glossary.xml">
-    <xi:fallback />
-  </xi:include>
-
-
-</book>
diff --git a/docs/reference/libsoup-3.0-sections.txt b/docs/reference/libsoup-3.0-sections.txt
deleted file mode 100644
index a5b8ac44..00000000
--- a/docs/reference/libsoup-3.0-sections.txt
+++ /dev/null
@@ -1,1037 +0,0 @@
-<INCLUDE>libsoup/soup.h</INCLUDE>
-<SECTION>
-<FILE>soup-message</FILE>
-<TITLE>SoupMessage</TITLE>
-SoupMessage
-<SUBSECTION>
-soup_message_new
-soup_message_new_from_uri
-soup_message_new_from_encoded_form
-soup_message_new_from_multipart
-soup_message_set_request_body
-soup_message_set_request_body_from_bytes
-<SUBSECTION>
-soup_message_new_options_ping
-soup_message_get_is_options_ping
-soup_message_set_is_options_ping
-<SUBSECTION>
-SoupHTTPVersion
-soup_message_get_http_version
-soup_message_get_uri
-soup_message_set_uri
-soup_message_get_method
-soup_message_set_method
-soup_message_get_status
-soup_message_get_reason_phrase
-<SUBSECTION>
-soup_message_get_request_headers
-soup_message_get_response_headers
-<SUBSECTION>
-soup_message_is_keepalive
-soup_message_get_connection_id
-soup_message_get_remote_address
-soup_message_get_tls_peer_certificate
-soup_message_get_tls_peer_certificate_errors
-soup_message_get_tls_protocol_version
-soup_message_get_tls_ciphersuite_name
-soup_message_set_tls_client_certificate
-soup_message_tls_client_certificate_password_request_complete
-<SUBSECTION>
-soup_message_set_first_party
-soup_message_get_first_party
-<SUBSECTION>
-soup_message_add_header_handler
-soup_message_add_status_code_handler
-<SUBSECTION>
-SoupMessageFlags
-soup_message_set_flags
-soup_message_get_flags
-soup_message_add_flags
-soup_message_remove_flags
-soup_message_query_flags
-<SUBSECTION>
-soup_message_disable_feature
-soup_message_is_feature_disabled
-<SUBSECTION>
-SoupMessagePriority
-soup_message_get_priority
-soup_message_set_priority
-<SUBSECTION>
-soup_message_get_site_for_cookies
-soup_message_set_site_for_cookies
-soup_message_get_is_top_level_navigation
-soup_message_set_is_top_level_navigation
-<SUBSECTION>
-soup_message_get_metrics
-<SUBSECTION Standard>
-SOUP_MESSAGE
-SOUP_IS_MESSAGE
-SOUP_TYPE_MESSAGE
-soup_message_get_type
-SOUP_MESSAGE_CLASS
-SOUP_IS_MESSAGE_CLASS
-SOUP_MESSAGE_GET_CLASS
-SoupMessageClass
-<SUBSECTION Private>
-soup_message_wrote_headers
-soup_message_wrote_body_data
-soup_message_wrote_body
-soup_message_got_informational
-soup_message_got_headers
-soup_message_content_sniffed
-soup_message_got_body
-soup_message_finished
-soup_message_restarted
-soup_message_starting
-</SECTION>
-
-<SECTION>
-<FILE>soup-method</FILE>
-<TITLE>SoupMethod</TITLE>
-SOUP_METHOD_OPTIONS
-SOUP_METHOD_GET
-SOUP_METHOD_HEAD
-SOUP_METHOD_PUT
-SOUP_METHOD_POST
-SOUP_METHOD_DELETE
-SOUP_METHOD_TRACE
-SOUP_METHOD_CONNECT
-<SUBSECTION>
-SOUP_METHOD_PROPFIND
-SOUP_METHOD_PROPPATCH
-SOUP_METHOD_MKCOL
-SOUP_METHOD_COPY
-SOUP_METHOD_MOVE
-SOUP_METHOD_LOCK
-SOUP_METHOD_UNLOCK
-</SECTION>
-
-<SECTION>
-<FILE>soup-message-headers</FILE>
-<TITLE>SoupMessageHeaders</TITLE>
-SoupMessageHeaders
-SoupMessageHeadersType
-soup_message_headers_new
-soup_message_headers_ref
-soup_message_headers_unref
-<SUBSECTION>
-soup_message_headers_append
-soup_message_headers_replace
-soup_message_headers_remove
-soup_message_headers_clear
-soup_message_headers_clean_connection_headers
-soup_message_headers_get_one
-soup_message_headers_get_list
-soup_message_headers_get_headers_type
-<SUBSECTION>
-soup_message_headers_header_contains
-soup_message_headers_header_equals
-<SUBSECTION>
-SoupMessageHeadersForeachFunc
-soup_message_headers_foreach
-<SUBSECTION>
-SoupMessageHeadersIter
-soup_message_headers_iter_init
-soup_message_headers_iter_next
-<SUBSECTION>
-SoupEncoding
-soup_message_headers_get_encoding
-soup_message_headers_set_encoding
-soup_message_headers_get_content_length
-soup_message_headers_set_content_length
-<SUBSECTION>
-SoupExpectation
-soup_message_headers_get_expectations
-soup_message_headers_set_expectations
-<SUBSECTION>
-soup_message_headers_get_content_type
-soup_message_headers_set_content_type
-<SUBSECTION>
-soup_message_headers_get_content_disposition
-soup_message_headers_set_content_disposition
-<SUBSECTION>
-SoupRange
-soup_message_headers_get_ranges
-soup_message_headers_set_ranges
-soup_message_headers_set_range
-soup_message_headers_free_ranges
-soup_message_headers_get_content_range
-soup_message_headers_set_content_range
-<SUBSECTION Standard>
-SOUP_TYPE_MESSAGE_HEADERS
-soup_message_headers_get_type
-</SECTION>
-
-<SECTION>
-<FILE>soup-headers</FILE>
-soup_headers_parse_request
-soup_headers_parse_response
-soup_headers_parse_status_line
-soup_headers_parse
-<SUBSECTION>
-soup_header_parse_list
-soup_header_parse_quality_list
-soup_header_free_list
-soup_header_contains
-soup_header_parse_param_list
-soup_header_parse_semi_param_list
-soup_header_parse_param_list_strict
-soup_header_parse_semi_param_list_strict
-soup_header_free_param_list
-soup_header_g_string_append_param
-soup_header_g_string_append_param_quoted
-</SECTION>
-
-<SECTION>
-<FILE>soup-message-body</FILE>
-<TITLE>SoupMessageBody</TITLE>
-SoupMemoryUse
-<SUBSECTION>
-SoupMessageBody
-soup_message_body_new
-soup_message_body_ref
-soup_message_body_unref
-<SUBSECTION>
-soup_message_body_set_accumulate
-soup_message_body_get_accumulate
-<SUBSECTION>
-soup_message_body_append
-soup_message_body_append_bytes
-soup_message_body_append_take
-soup_message_body_truncate
-soup_message_body_complete
-soup_message_body_flatten
-soup_message_body_get_chunk
-<SUBSECTION>
-soup_message_body_got_chunk
-soup_message_body_wrote_chunk
-<SUBSECTION Standard>
-SOUP_TYPE_MESSAGE_BODY
-soup_message_body_get_type
-</SECTION>
-
-<SECTION>
-<FILE>soup-status</FILE>
-<TITLE>SoupStatus</TITLE>
-SOUP_STATUS_IS_INFORMATIONAL
-SOUP_STATUS_IS_SUCCESSFUL
-SOUP_STATUS_IS_REDIRECTION
-SOUP_STATUS_IS_CLIENT_ERROR
-SOUP_STATUS_IS_SERVER_ERROR
-SoupStatus
-soup_status_get_phrase
-</SECTION>
-
-<SECTION>
-<FILE>soup-server</FILE>
-<TITLE>SoupServer</TITLE>
-SoupServer
-soup_server_new
-soup_server_set_tls_certificate
-soup_server_get_tls_certificate
-soup_server_set_tls_database
-soup_server_get_tls_database
-soup_server_set_tls_auth_mode
-soup_server_get_tls_auth_mode
-<SUBSECTION>
-SoupServerListenOptions
-soup_server_listen
-soup_server_listen_all
-soup_server_listen_local
-soup_server_listen_socket
-soup_server_get_listeners
-soup_server_get_uris
-soup_server_disconnect
-soup_server_is_https
-soup_server_accept_iostream
-<SUBSECTION>
-SoupServerCallback
-soup_server_add_handler
-soup_server_add_early_handler
-soup_server_remove_handler
-<SUBSECTION>
-SoupServerWebsocketCallback
-soup_server_add_websocket_handler
-soup_server_add_websocket_extension
-soup_server_remove_websocket_extension
-<SUBSECTION>
-soup_server_add_auth_domain
-soup_server_remove_auth_domain
-soup_server_pause_message
-soup_server_unpause_message
-<SUBSECTION Standard>
-SOUP_SERVER
-SOUP_IS_SERVER
-SOUP_TYPE_SERVER
-soup_server_get_type
-SOUP_SERVER_CLASS
-SOUP_IS_SERVER_CLASS
-SOUP_SERVER_GET_CLASS
-SoupServerClass
-SOUP_TYPE_CLIENT_CONTEXT
-soup_client_context_get_type
-</SECTION>
-
-<SECTION>
-<FILE>soup-server-message</FILE>
-<TITLE>SoupServerMessage</TITLE>
-SoupServerMessage
-soup_server_message_get_request_headers
-soup_server_message_get_response_headers
-soup_server_message_get_request_body
-soup_server_message_get_response_body
-soup_server_message_get_method
-soup_server_message_get_http_version
-soup_server_message_set_http_version
-soup_server_message_get_status
-soup_server_message_set_status
-soup_server_message_get_reason_phrase
-soup_server_message_get_uri
-soup_server_message_set_response
-soup_server_message_set_redirect
-soup_server_message_get_socket
-soup_server_message_get_local_address
-soup_server_message_get_remote_address
-soup_server_message_get_remote_host
-soup_server_message_is_options_ping
-soup_server_message_steal_connection
-<SUBSECTION Standard>
-SOUP_SERVER_MESSAGE
-SOUP_IS_SERVER_MESSAGE
-SOUP_TYPE_SERVER_MESSAGE
-<SUBSECTION Private>
-soup_server_message_get_type
-</SECTION>
-
-<SECTION>
-<FILE>soup-auth-domain</FILE>
-<TITLE>SoupAuthDomain</TITLE>
-SoupAuthDomain
-<SUBSECTION>
-SoupAuthDomainFilter
-soup_auth_domain_set_filter
-soup_auth_domain_get_realm
-<SUBSECTION>
-soup_auth_domain_add_path
-soup_auth_domain_remove_path
-<SUBSECTION>
-SoupAuthDomainGenericAuthCallback
-soup_auth_domain_set_generic_auth_callback
-soup_auth_domain_check_password
-<SUBSECTION>
-soup_auth_domain_covers
-soup_auth_domain_accepts
-soup_auth_domain_challenge
-<SUBSECTION Private>
-soup_auth_domain_try_generic_auth_callback
-<SUBSECTION Standard>
-SOUP_AUTH_DOMAIN
-SOUP_IS_AUTH_DOMAIN
-SOUP_TYPE_AUTH_DOMAIN
-soup_auth_domain_get_type
-SOUP_AUTH_DOMAIN_CLASS
-SOUP_IS_AUTH_DOMAIN_CLASS
-SOUP_AUTH_DOMAIN_GET_CLASS
-SoupAuthDomainClass
-</SECTION>
-
-<SECTION>
-<FILE>soup-auth-domain-basic</FILE>
-<TITLE>SoupAuthDomainBasic</TITLE>
-SoupAuthDomainBasic
-soup_auth_domain_basic_new
-<SUBSECTION>
-SoupAuthDomainBasicAuthCallback
-soup_auth_domain_basic_set_auth_callback
-<SUBSECTION Standard>
-SOUP_AUTH_DOMAIN_BASIC
-SOUP_IS_AUTH_DOMAIN_BASIC
-SOUP_TYPE_AUTH_DOMAIN_BASIC
-soup_auth_domain_basic_get_type
-SOUP_AUTH_DOMAIN_BASIC_CLASS
-SOUP_IS_AUTH_DOMAIN_BASIC_CLASS
-SOUP_AUTH_DOMAIN_BASIC_GET_CLASS
-SoupAuthDomainBasicClass
-</SECTION>
-
-<SECTION>
-<FILE>soup-auth-domain-digest</FILE>
-<TITLE>SoupAuthDomainDigest</TITLE>
-SoupAuthDomainDigest
-soup_auth_domain_digest_new
-<SUBSECTION>
-SoupAuthDomainDigestAuthCallback
-soup_auth_domain_digest_set_auth_callback
-soup_auth_domain_digest_encode_password
-<SUBSECTION Standard>
-SOUP_AUTH_DOMAIN_DIGEST
-SOUP_IS_AUTH_DOMAIN_DIGEST
-SOUP_TYPE_AUTH_DOMAIN_DIGEST
-soup_auth_domain_digest_get_type
-SOUP_AUTH_DOMAIN_DIGEST_CLASS
-SOUP_IS_AUTH_DOMAIN_DIGEST_CLASS
-SOUP_AUTH_DOMAIN_DIGEST_GET_CLASS
-SoupAuthDomainDigestClass
-</SECTION>
-
-<SECTION>
-<FILE>soup-session</FILE>
-<TITLE>SoupSession</TITLE>
-SoupSession
-SoupSessionError
-<SUBSECTION>
-soup_session_new
-soup_session_new_with_options
-<SUBSECTION>
-soup_session_get_local_address
-soup_session_get_max_conns
-soup_session_get_max_conns_per_host
-soup_session_set_proxy_resolver
-soup_session_get_proxy_resolver
-soup_session_set_tls_database
-soup_session_get_tls_database
-soup_session_set_tls_interaction
-soup_session_get_tls_interaction
-soup_session_set_timeout
-soup_session_get_timeout
-soup_session_set_idle_timeout
-soup_session_get_idle_timeout
-soup_session_set_user_agent
-soup_session_get_user_agent
-soup_session_set_accept_language
-soup_session_get_accept_language
-soup_session_set_accept_language_auto
-soup_session_get_accept_language_auto
-soup_session_get_async_result_message
-soup_session_get_remote_connectable
-<SUBSECTION>
-soup_session_send
-soup_session_send_async
-soup_session_send_finish
-soup_session_send_and_read
-soup_session_send_and_read_async
-soup_session_send_and_read_finish
-<SUBSECTION>
-soup_session_websocket_connect_async
-soup_session_websocket_connect_finish
-<SUBSECTION>
-soup_session_abort
-<SUBSECTION>
-soup_session_add_feature
-soup_session_add_feature_by_type
-soup_session_remove_feature
-soup_session_remove_feature_by_type
-soup_session_get_feature
-soup_session_get_feature_for_message
-soup_session_has_feature
-<SUBSECTION>
-soup_session_preconnect_async
-soup_session_preconnect_finish
-<SUBSECTION Standard>
-SOUP_IS_SESSION
-SOUP_IS_SESSION_CLASS
-SOUP_SESSION
-SOUP_SESSION_CLASS
-SOUP_SESSION_GET_CLASS
-SOUP_TYPE_SESSION
-SOUP_SESSION_ERROR
-SoupSessionClass
-soup_session_get_type
-soup_session_error_quark
-<SUBSECTION Private>
-SoupSocket
-SoupConnection
-SoupConnectionState
-SOUP_TYPE_CONNECTION_STATE
-soup_connection_state_get_type
-SoupMessageQueue
-SoupMessageQueueItem
-SOUP_SESSION_USE_NTLM
-SoupClientMessageIO
-</SECTION>
-
-<SECTION>
-<FILE>soup-session-feature</FILE>
-<TITLE>SoupSessionFeature</TITLE>
-SoupSessionFeature
-<SUBSECTION Standard>
-soup_session_feature_get_type
-SOUP_SESSION_FEATURE
-SOUP_SESSION_FEATURE_CLASS
-SOUP_SESSION_FEATURE_GET_CLASS
-SOUP_IS_SESSION_FEATURE
-SOUP_IS_SESSION_FEATURE_CLASS
-SOUP_TYPE_SESSION_FEATURE
-</SECTION>
-
-<SECTION>
-<FILE>soup-auth</FILE>
-<TITLE>SoupAuth</TITLE>
-SoupAuth
-soup_auth_new
-soup_auth_update
-<SUBSECTION>
-SOUP_TYPE_AUTH_BASIC
-SOUP_TYPE_AUTH_DIGEST
-SOUP_TYPE_AUTH_NTLM
-SOUP_TYPE_AUTH_NEGOTIATE
-soup_auth_negotiate_supported
-<SUBSECTION>
-soup_auth_is_for_proxy
-soup_auth_get_scheme_name
-soup_auth_get_authority
-soup_auth_get_realm
-soup_auth_get_info
-<SUBSECTION>
-soup_auth_authenticate
-soup_auth_can_authenticate
-soup_auth_is_authenticated
-soup_auth_is_ready
-soup_auth_cancel
-soup_auth_is_cancelled
-<SUBSECTION>
-soup_auth_get_authorization
-soup_auth_get_protection_space
-soup_auth_free_protection_space
-<SUBSECTION Private>
-SoupAuthBasic
-SoupAuthDigest
-SoupAuthNTLM
-SoupAuthNegotiate
-<SUBSECTION Standard>
-SOUP_AUTH
-SOUP_IS_AUTH
-SOUP_TYPE_AUTH
-soup_auth_get_type
-SOUP_AUTH_CLASS
-SOUP_IS_AUTH_CLASS
-SOUP_AUTH_GET_CLASS
-SoupAuthClass
-soup_auth_basic_get_type
-soup_auth_digest_get_type
-soup_auth_ntlm_get_type
-soup_auth_negotiate_get_type
-</SECTION>
-
-<SECTION>
-<FILE>soup-auth-manager</FILE>
-<TITLE>SoupAuthManager</TITLE>
-SoupAuthManager
-SOUP_TYPE_AUTH_MANAGER
-soup_auth_manager_use_auth
-soup_auth_manager_clear_cached_credentials
-<SUBSECTION Standard>
-SoupAuthManagerPrivate
-SoupAuthManagerClass
-SOUP_AUTH_MANAGER
-SOUP_IS_AUTH_MANAGER
-SOUP_AUTH_MANAGER_CLASS
-SOUP_IS_AUTH_MANAGER_CLASS
-SOUP_AUTH_MANAGER_GET_CLASS
-soup_auth_manager_get_type
-</SECTION>
-
-<SECTION>
-<FILE>soup-date-utils</FILE>
-SoupDateFormat
-soup_date_time_new_from_http_string
-soup_date_time_to_string
-<SUBSECTION Private>
-soup_date_time_is_past
-</SECTION>
-
-<SECTION>
-<FILE>soup-uri-utils</FILE>
-soup_uri_equal
-<SUBSECTION>
-SOUP_HTTP_URI_FLAGS
-<SUBSECTION>
-soup_uri_decode_data_uri
-<SUBSECTION>
-SoupURIComponent
-soup_uri_copy
-</SECTION>
-
-<SECTION>
-<FILE>soup-form</FILE>
-<TITLE>SoupForm</TITLE>
-<SUBSECTION>
-SOUP_FORM_MIME_TYPE_MULTIPART
-SOUP_FORM_MIME_TYPE_URLENCODED
-soup_form_decode
-soup_form_decode_multipart
-soup_form_encode
-soup_form_encode_datalist
-soup_form_encode_hash
-soup_form_encode_valist
-</SECTION>
-
-<SECTION>
-<FILE>soup-logger</FILE>
-<TITLE>SoupLogger</TITLE>
-SoupLogger
-SoupLoggerLogLevel
-soup_logger_new
-soup_logger_set_max_body_size
-soup_logger_get_max_body_size
-<SUBSECTION>
-SoupLoggerFilter
-soup_logger_set_request_filter
-soup_logger_set_response_filter
-<SUBSECTION>
-SoupLoggerPrinter
-soup_logger_set_printer
-<SUBSECTION Standard>
-SoupLoggerClass
-soup_logger_get_type
-SOUP_IS_LOGGER
-SOUP_IS_LOGGER_CLASS
-SOUP_LOGGER
-SOUP_LOGGER_CLASS
-SOUP_LOGGER_GET_CLASS
-SOUP_TYPE_LOGGER
-</SECTION>
-
-<SECTION>
-<FILE>soup-cookie</FILE>
-<TITLE>SoupCookie</TITLE>
-SoupCookie
-soup_cookie_new
-soup_cookie_parse
-soup_cookie_copy
-soup_cookie_free
-<SUBSECTION>
-soup_cookie_set_name
-soup_cookie_get_name
-soup_cookie_set_value
-soup_cookie_get_value
-soup_cookie_set_domain
-soup_cookie_get_domain
-soup_cookie_set_path
-soup_cookie_get_path
-soup_cookie_set_max_age
-SOUP_COOKIE_MAX_AGE_ONE_HOUR
-SOUP_COOKIE_MAX_AGE_ONE_DAY
-SOUP_COOKIE_MAX_AGE_ONE_WEEK
-SOUP_COOKIE_MAX_AGE_ONE_YEAR
-soup_cookie_set_expires
-soup_cookie_get_expires
-soup_cookie_set_secure
-soup_cookie_get_secure
-soup_cookie_set_http_only
-soup_cookie_get_http_only
-<SUBSECTION>
-SoupSameSitePolicy
-soup_cookie_set_same_site_policy
-soup_cookie_get_same_site_policy
-<SUBSECTION>
-soup_cookie_applies_to_uri
-soup_cookie_domain_matches
-<SUBSECTION>
-soup_cookie_to_cookie_header
-soup_cookie_to_set_cookie_header
-<SUBSECTION>
-soup_cookies_from_request
-soup_cookies_from_response
-soup_cookies_to_request
-soup_cookies_to_response
-soup_cookies_to_cookie_header
-soup_cookies_free
-<SUBSECTION Standard>
-SOUP_TYPE_COOKIE
-soup_cookie_get_type
-<SUBSECTION Private>
-soup_cookie_equal
-</SECTION>
-
-<SECTION>
-<FILE>soup-cookie-jar</FILE>
-<TITLE>SoupCookieJar</TITLE>
-SoupCookieJar
-soup_cookie_jar_new
-soup_cookie_jar_get_cookies
-soup_cookie_jar_get_cookie_list
-soup_cookie_jar_get_cookie_list_with_same_site_info
-soup_cookie_jar_set_cookie
-soup_cookie_jar_set_cookie_with_first_party
-<SUBSECTION>
-soup_cookie_jar_add_cookie
-soup_cookie_jar_add_cookie_with_first_party
-soup_cookie_jar_add_cookie_full
-soup_cookie_jar_delete_cookie
-soup_cookie_jar_all_cookies
-<SUBSECTION>
-SoupCookieJarAcceptPolicy
-soup_cookie_jar_get_accept_policy
-soup_cookie_jar_set_accept_policy
-<SUBSECTION>
-soup_cookie_jar_is_persistent
-<SUBSECTION Standard>
-SoupCookieJarClass
-SOUP_COOKIE_JAR
-SOUP_COOKIE_JAR_CLASS
-SOUP_COOKIE_JAR_GET_CLASS
-SOUP_IS_COOKIE_JAR
-SOUP_IS_COOKIE_JAR_CLASS
-SOUP_TYPE_COOKIE_JAR
-soup_cookie_jar_get_type
-</SECTION>
-
-<SECTION>
-<FILE>soup-multipart</FILE>
-<TITLE>SoupMultipart</TITLE>
-SoupMultipart
-soup_multipart_new
-soup_multipart_new_from_message
-soup_multipart_free
-<SUBSECTION>
-soup_multipart_get_length
-soup_multipart_get_part
-soup_multipart_append_part
-soup_multipart_append_form_string
-soup_multipart_append_form_file
-soup_multipart_to_message
-<SUBSECTION Standard>
-SOUP_TYPE_MULTIPART
-soup_multipart_get_type
-</SECTION>
-
-<SECTION>
-<FILE>soup-multipart-input-stream</FILE>
-<TITLE>SoupMultipartInputStream</TITLE>
-SoupMultipartInputStream
-soup_multipart_input_stream_new
-<SUBSECTION>
-soup_multipart_input_stream_get_headers
-soup_multipart_input_stream_next_part
-soup_multipart_input_stream_next_part_async
-soup_multipart_input_stream_next_part_finish
-<SUBSECTION Standard>
-SOUP_IS_MULTIPART_INPUT_STREAM
-SOUP_IS_MULTIPART_INPUT_STREAM_CLASS
-SOUP_MULTIPART_INPUT_STREAM
-SOUP_MULTIPART_INPUT_STREAM_CLASS
-SOUP_MULTIPART_INPUT_STREAM_GET_CLASS
-SOUP_TYPE_MULTIPART_INPUT_STREAM
-soup_multipart_input_stream_get_type
-SoupMultipartInputStreamPrivate
-</SECTION>
-
-<SECTION>
-<FILE>soup-cookie-jar-text</FILE>
-<TITLE>SoupCookieJarText</TITLE>
-SoupCookieJarText
-soup_cookie_jar_text_new
-<SUBSECTION Standard>
-SoupCookieJarTextClass
-SOUP_COOKIE_JAR_TEXT
-SOUP_COOKIE_JAR_TEXT_CLASS
-SOUP_COOKIE_JAR_TEXT_GET_CLASS
-SOUP_TYPE_COOKIE_JAR_TEXT
-SOUP_IS_COOKIE_JAR_TEXT
-SOUP_IS_COOKIE_JAR_TEXT_CLASS
-soup_cookie_jar_text_get_type
-</SECTION>
-
-<SECTION>
-<FILE>soup-cookie-jar-db</FILE>
-<TITLE>SoupCookieJarDB</TITLE>
-SoupCookieJarDB
-soup_cookie_jar_db_new
-<SUBSECTION Standard>
-SoupCookieJarDBClass
-SOUP_COOKIE_JAR_DB
-SOUP_COOKIE_JAR_DB_CLASS
-SOUP_COOKIE_JAR_DB_GET_CLASS
-SOUP_TYPE_COOKIE_JAR_DB
-SOUP_IS_COOKIE_JAR_DB
-SOUP_IS_COOKIE_JAR_DB_CLASS
-soup_cookie_jar_db_get_type
-</SECTION>
-
-<SECTION>
-<FILE>soup-content-sniffer</FILE>
-<TITLE>SoupContentSniffer</TITLE>
-SoupContentSniffer
-soup_content_sniffer_new
-soup_content_sniffer_sniff
-<SUBSECTION Standard>
-SOUP_CONTENT_SNIFFER
-SOUP_CONTENT_SNIFFER_CLASS
-SOUP_CONTENT_SNIFFER_GET_CLASS
-SOUP_IS_CONTENT_SNIFFER
-SOUP_IS_CONTENT_SNIFFER_CLASS
-SOUP_TYPE_CONTENT_SNIFFER
-SoupContentSnifferClass
-SoupContentSnifferPrivate
-soup_content_sniffer_get_type
-</SECTION>
-
-<SECTION>
-<FILE>soup-cache</FILE>
-<TITLE>SoupCache</TITLE>
-SoupCache
-SoupCacheType
-soup_cache_new
-soup_cache_flush
-soup_cache_clear
-soup_cache_dump
-soup_cache_load
-soup_cache_get_max_size
-soup_cache_set_max_size
-<SUBSECTION Standard>
-SOUP_TYPE_CACHE
-SOUP_IS_CACHE
-SOUP_IS_CACHE_CLASS
-SOUP_CACHE
-SOUP_CACHE_CLASS
-SOUP_CACHE_GET_CLASS
-SoupCacheClass
-SoupCachePrivate
-<SUBSECTION Private>
-soup_cache_get_type
-SoupCacheResponse
-SoupCacheability
-</SECTION>
-
-<SECTION>
-<FILE>soup-content-decoder</FILE>
-<TITLE>SoupContentDecoder</TITLE>
-SoupContentDecoder
-<SUBSECTION Standard>
-SOUP_TYPE_CONTENT_DECODER
-SOUP_IS_CONTENT_DECODER
-SOUP_IS_CONTENT_DECODER_CLASS
-SOUP_CONTENT_DECODER
-SOUP_CONTENT_DECODER_CLASS
-SOUP_CONTENT_DECODER_GET_CLASS
-SoupContentDecoderClass
-SoupContentDecoderPrivate
-soup_content_decoder_get_type
-</SECTION>
-
-<SECTION>
-<FILE>soup-tld</FILE>
-<TITLE>SoupTLD</TITLE>
-<SUBSECTION>
-soup_tld_get_base_domain
-soup_tld_domain_is_public_suffix
-<SUBSECTION>
-SOUP_TLD_ERROR
-SoupTLDError
-<SUBSECTION Private>
-soup_tld_error_quark
-</SECTION>
-
-<SECTION>
-<FILE>soup-version</FILE>
-<TITLE>Version Information</TITLE>
-soup_get_major_version
-soup_get_minor_version
-soup_get_micro_version
-soup_check_version
-<SUBSECTION>
-SOUP_MAJOR_VERSION
-SOUP_MINOR_VERSION
-SOUP_MICRO_VERSION
-SOUP_CHECK_VERSION
-<SUBSECTION>
-SOUP_VERSION_MIN_REQUIRED
-SOUP_VERSION_MAX_ALLOWED
-SOUP_VERSION_3_0
-SOUP_VERSION_3_2
-<SUBSECTION Private>
-SOUP_AVAILABLE_IN_ALL
-SOUP_AVAILABLE_IN_3_0
-SOUP_DEPRECATED_IN_3_0
-SOUP_DEPRECATED_IN_3_0_FOR
-SOUP_AVAILABLE_IN_3_2
-SOUP_DEPRECATED_IN_3_2
-SOUP_DEPRECATED_IN_3_2_FOR
-SOUP_ENCODE_VERSION
-SOUP_VAR
-SOUP_VERSION_CUR_STABLE
-SOUP_VERSION_PREV_STABLE
-</SECTION>
-
-<SECTION>
-<FILE>soup-websocket</FILE>
-<TITLE>SoupWebsocket</TITLE>
-soup_websocket_client_prepare_handshake
-soup_websocket_client_verify_handshake
-<SUBSECTION>
-soup_websocket_server_check_handshake
-soup_websocket_server_process_handshake
-<SUBSECTION>
-SoupWebsocketConnection
-SoupWebsocketConnectionType
-soup_websocket_connection_new
-soup_websocket_connection_get_io_stream
-soup_websocket_connection_get_connection_type
-soup_websocket_connection_get_uri
-soup_websocket_connection_get_origin
-soup_websocket_connection_get_protocol
-soup_websocket_connection_get_extensions
-soup_websocket_connection_get_max_incoming_payload_size
-soup_websocket_connection_set_max_incoming_payload_size
-soup_websocket_connection_get_keepalive_interval
-soup_websocket_connection_set_keepalive_interval
-SoupWebsocketState
-soup_websocket_connection_get_state
-SoupWebsocketDataType
-soup_websocket_connection_send_text
-soup_websocket_connection_send_binary
-soup_websocket_connection_send_message
-SoupWebsocketCloseCode
-soup_websocket_connection_close
-soup_websocket_connection_get_close_code
-soup_websocket_connection_get_close_data
-<SUBSECTION>
-SoupWebsocketError
-SOUP_WEBSOCKET_ERROR
-<SUBSECTION Standard>
-SoupWebsocketConnectionClass
-SoupWebsocketConnectionPrivate
-SOUP_IS_WEBSOCKET_CONNECTION
-SOUP_IS_WEBSOCKET_CONNECTION_CLASS
-SOUP_TYPE_WEBSOCKET_CONNECTION
-SOUP_WEBSOCKET_CONNECTION
-SOUP_WEBSOCKET_CONNECTION_CLASS
-SOUP_WEBSOCKET_CONNECTION_GET_CLASS
-soup_websocket_close_code_get_type
-soup_websocket_connection_get_type
-soup_websocket_connection_type_get_type
-soup_websocket_data_type_get_type
-soup_websocket_error_quark
-soup_websocket_error_get_type
-soup_websocket_state_get_type
-</SECTION>
-
-<SECTION>
-<FILE>soup-websocket-extension</FILE>
-<TITLE>SoupWebsocketExtension</TITLE>
-SoupWebsocketExtension
-soup_websocket_extension_configure
-soup_websocket_extension_get_request_params
-soup_websocket_extension_get_response_params
-soup_websocket_extension_process_outgoing_message
-soup_websocket_extension_process_incoming_message
-<SUBSECTION>
-SoupWebsocketExtensionClass
-<SUBSECTION>
-SoupWebsocketExtensionDeflate
-SOUP_TYPE_WEBSOCKET_EXTENSION_DEFLATE
-<SUBSECTION>
-SoupWebsocketExtensionManager
-SOUP_TYPE_WEBSOCKET_EXTENSION_MANAGER
-<SUBSECTION Standard>
-soup_websocket_extension_get_type
-SOUP_IS_WEBSOCKET_EXTENSION
-SOUP_IS_WEBSOCKET_EXTENSION_CLASS
-SOUP_TYPE_WEBSOCKET_EXTENSION
-SOUP_WEBSOCKET_EXTENSION
-SOUP_WEBSOCKET_EXTENSION_CLASS
-SOUP_WEBSOCKET_EXTENSION_GET_CLASS
-SOUP_IS_WEBSOCKET_EXTENSION_DEFLATE
-SOUP_IS_WEBSOCKET_EXTENSION_DEFLATE_CLASS
-SOUP_WEBSOCKET_EXTENSION_DEFLATE
-SOUP_WEBSOCKET_EXTENSION_DEFLATE_CLASS
-SOUP_WEBSOCKET_EXTENSION_DEFLATE_GET_CLASS
-soup_websocket_extension_deflate_get_type
-SoupWebsocketExtensionDeflateClass
-SoupWebsocketExtensionManagerClass
-soup_websocket_extension_manager_get_type
-SOUP_IS_WEBSOCKET_EXTENSION_MANAGER
-SOUP_IS_WEBSOCKET_EXTENSION_MANAGER_CLASS
-SOUP_WEBSOCKET_EXTENSION_MANAGER
-SOUP_WEBSOCKET_EXTENSION_MANAGER_CLASS
-SOUP_WEBSOCKET_EXTENSION_MANAGER_GET_CLASS
-</SECTION>
-
-<SECTION>
-<FILE>soup-hsts-enforcer</FILE>
-<TITLE>SoupHSTSEnforcer</TITLE>
-SoupHSTSEnforcer
-SoupHSTSEnforcerClass
-soup_hsts_enforcer_new
-soup_hsts_enforcer_is_persistent
-soup_hsts_enforcer_has_valid_policy
-soup_hsts_enforcer_set_policy
-soup_hsts_enforcer_set_session_policy
-soup_hsts_enforcer_get_domains
-soup_hsts_enforcer_get_policies
-<SUBSECTION Standard>
-SOUP_HSTS_ENFORCER
-SOUP_HSTS_ENFORCER_CLASS
-SOUP_HSTS_ENFORCER_GET_CLASS
-SOUP_TYPE_HSTS_ENFORCER
-SOUP_IS_HSTS_ENFORCER
-SOUP_IS_HSTS_ENFORCER_CLASS
-soup_hsts_enforcer_get_type
-</SECTION>
-
-<SECTION>
-<FILE>soup-hsts-policy</FILE>
-SoupHSTSPolicy
-soup_hsts_policy_new
-soup_hsts_policy_new_full
-soup_hsts_policy_new_session_policy
-soup_hsts_policy_new_from_response
-soup_hsts_policy_copy
-soup_hsts_policy_equal
-soup_hsts_policy_free
-soup_hsts_policy_get_domain
-soup_hsts_policy_get_max_age
-soup_hsts_policy_get_expires
-soup_hsts_policy_is_expired
-soup_hsts_policy_includes_subdomains
-soup_hsts_policy_is_session_policy
-SOUP_HSTS_POLICY_MAX_AGE_PAST
-<SUBSECTION Standard>
-SOUP_TYPE_HSTS_POLICY
-soup_hsts_policy_get_type
-</SECTION>
-
-<SECTION>
-<FILE>soup-hsts-enforcer-db</FILE>
-<TITLE>SoupHSTSEnforcerDB</TITLE>
-SoupHSTSEnforcerDB
-soup_hsts_enforcer_db_new
-<SUBSECTION Standard>
-SoupHSTSEnforcerDBClass
-SOUP_HSTS_ENFORCER_DB
-SOUP_HSTS_ENFORCER_DB_CLASS
-SOUP_HSTS_ENFORCER_DB_GET_CLASS
-SOUP_TYPE_HSTS_ENFORCER_DB
-SOUP_IS_HSTS_ENFORCER_DB
-SOUP_IS_HSTS_ENFORCER_DB_CLASS
-soup_hsts_enforcer_db_get_type
-</SECTION>
-
-<SECTION>
-<FILE>soup-message-metrics</FILE>
-<TITLE>SoupMessageMetrics</TITLE>
-SoupMessageMetrics
-soup_message_metrics_copy
-soup_message_metrics_free
-<SUBSECTION>
-soup_message_metrics_get_fetch_start
-soup_message_metrics_get_dns_start
-soup_message_metrics_get_dns_end
-soup_message_metrics_get_connect_start
-soup_message_metrics_get_connect_end
-soup_message_metrics_get_tls_start
-soup_message_metrics_get_request_start
-soup_message_metrics_get_response_start
-soup_message_metrics_get_response_end
-<SUBSECTION>
-soup_message_metrics_get_request_header_bytes_sent
-soup_message_metrics_get_request_body_size
-soup_message_metrics_get_request_body_bytes_sent
-soup_message_metrics_get_response_header_bytes_received
-soup_message_metrics_get_response_body_size
-soup_message_metrics_get_response_body_bytes_received
-<SUBSECTION Standard>
-SOUP_TYPE_MESSAGE_METRICS
-soup_message_metrics_get_type
-</SECTION>
diff --git a/docs/reference/libsoup.toml.in b/docs/reference/libsoup.toml.in
new file mode 100644
index 00000000..775ff3bd
--- /dev/null
+++ b/docs/reference/libsoup.toml.in
@@ -0,0 +1,50 @@
+[library]
+version = "@VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/libsoup"
+repository_url = "https://gitlab.gnome.org/GNOME/libsoup.git"
+docs_url = "https://gnome.pages.gitlab.gnome.org/libsoup/libsoup-3.0/"
+website_url = "https://libsoup.org/"
+authors = "Dan Winship, Claudio Saavedra, and Patrick Griffis"
+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/libsoup/-/blob/master/"
+
+[extra]
+# The same order will be used when generating the index
+content_files = [
+  "build-howto.md",
+  'client-basic.md',
+  'client-advanced.md',
+  'client-tls.md',
+  'server-howto.md',
+  "migrating-from-libsoup-2.md",
+]
+
+content_images = [
+]
+urlmap_file = "urlmap.js"
diff --git a/docs/reference/meson.build b/docs/reference/meson.build
index 70282eca..e36c2fd3 100644
--- a/docs/reference/meson.build
+++ b/docs/reference/meson.build
@@ -1,87 +1,46 @@
-ignore_headers = [
-  'gconstructor.h',
-  'soup.h',
-  'soup-enum-types.h',
-  'soup-message-private.h',
-  'soup-session-private.h',
-  'soup-auth-digest-private.h',
-  'soup-brotli-decompressor.h',
-  'soup-connection.h',
-  'soup-connection-auth.h',
-  'soup-message-queue-item.h',
-  'soup-path-map.h',
-  'soup-http-input-stream.h',
-  'soup-converter-wrapper.h',
-  'soup-body-input-stream.h',
-  'soup-body-output-stream.h',
-  'soup-client-input-stream.h',
-  'soup-content-processor.h',
-  'soup-content-sniffer-stream.h',
-  'soup-io-stream.h',
-  'soup-cache-input-stream.h',
-  'soup-filter-input-stream.h',
-  'soup-cookie-jar-sqlite.h',
-  'soup-cache-private.h',
-  'soup-cache-client-input-stream.h',
-  'soup-logger-input-stream.h',
-  'soup-logger-private.h',
-  'soup-socket.h',
-  'soup-socket-properties.h',
-  'soup-websocket-extension-manager-private.h',
-  'soup-misc.h',
-  'soup-date-utils-private.h',
-  'soup-resources.h',
-  'soup-private-enum-types.h',
-  'soup-server-message-private.h',
-  'soup-message-io-data.h',
-  'soup-message-io-source.h',
-  'soup-uri-utils-private.h',
-  'soup-session-feature-private.h',
-  'soup-message-metrics-private.h',
-  'soup-client-message-io.h',
-  'soup-message-io-completion.h',
-  'soup-client-message-io-http1.h',
-  'soup-client-message-io-http2.h',
-  'soup-body-input-stream-http2.h',
-  'soup-tls-interaction.h',
-  'soup-header-names.h',
-  'soup-message-headers-private.h',
+expand_content_md_files = [
+    'build-howto.md',
+    'client-basic.md',
+    'client-advanced.md',
+    'client-tls.md',
+    'server-howto.md',
+    'migrating-from-libsoup-2.md',
 ]
 
-mkdb_args = [
-  '--output-format=xml'
-]
+toml_data = configuration_data()
+toml_data.set('VERSION', meson.project_version())
 
-scan_args = [
-  '--deprecated-guards=SOUP_DISABLE_DEPRECATED',
-  '--rebuild-types',
-  '--ignore-decorators="SOUP_DEPRECATED\w*\s*()|SOUP_DEPRECATED\w*|SOUP_AVAILABLE[\w_]*"'
-]
+libsoup_toml = configure_file(
+  input: 'libsoup.toml.in',
+  output: 'libsoup.toml',
+  configuration: toml_data
+)
 
-glib_prefix = glib_dep.get_pkgconfig_variable('prefix')
-glib_docpath = glib_prefix / 'share' / 'gtk-doc' / 'html'
+dependency('gi-docgen', version: '>= 2021.1',
+           fallback: ['gi-docgen', 'dummy_dep'],
+           native: true,
+           required: get_option('gtk_doc'))
 
-gnome.gtkdoc('libsoup-3.0',
-  main_xml : 'libsoup-3.0-docs.xml',
-  src_dir : srcdir,
-  ignore_headers : ignore_headers,
-  namespace : 'soup',
-  mkdb_args : mkdb_args,
-  scan_args : scan_args,
-  fixxref_args : [
-    '--html-dir=@0@'.format(get_option('datadir') / 'gtk-doc', 'html'),
-    '--extra-dir=@0@'.format(glib_docpath / 'glib'),
-    '--extra-dir=@0@'.format(glib_docpath /'gobject'),
-    '--extra-dir=@0@'.format(glib_docpath /'gio'),
-  ],
-  dependencies : libsoup_dep,
-  install : true,
-  content_files: [
-    'build-howto.xml',
-    'client-basic.xml',
-    'client-advanced.xml',
-    'client-tls.xml',
-    'server-howto.xml',
-    'migrating-from-libsoup-2.xml',
+gidocgen = find_program('gi-docgen')
+
+docs_dir = get_option('datadir') / 'doc'
+
+custom_target('libsoup-doc',
+  input: [ libsoup_toml, soup_gir_gen_sources[0] ],
+  output: 'libsoup-@0@'.format(apiversion),
+  command: [
+    gidocgen,
+    'generate',
+    '--quiet',
+    '--add-include-path=@0@'.format(meson.current_build_dir() / '../../libsoup'),
+    '--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,
 )
diff --git a/docs/reference/migrating-from-libsoup-2.md b/docs/reference/migrating-from-libsoup-2.md
new file mode 100644
index 00000000..0c399aa5
--- /dev/null
+++ b/docs/reference/migrating-from-libsoup-2.md
@@ -0,0 +1,162 @@
+Title: Migrating from libsoup 2
+Slug: migrating-from-libsoup-2
+
+# Migrating from libsoup 2
+
+## Removed APIs
+
+This is a list of APIs that have been removed:
+
+ - XML-RPC support.
+ - Handling of `file://` and `data://` URIs You should use [iface@Gio.File] for
+   the former and [func@uri_decode_data_uri] for the latter.
+ - Define aliases for property names You must use the string name of properties
+   directly which works in libsoup 2 already.
+ - `SoupSession:add-feature` and `SoupSession:add-feature-by-type` You must call
+   [method@Session.add_feature] and [method@Session.add_feature_by_type]
+   directly.
+ - `SoupRequest`: You should use [method@Session.send] or
+   [method@Session.send_async] methods.
+ - `SoupAddress` has been replaced with [class@Gio.InetAddress] and
+   [class@Gio.NetworkAddress].
+ - `SoupSocket` has been removed.
+ - `SoupProxyResolverDefault` is replaced by
+   [func@Gio.ProxyResolver.get_default].
+ - `SoupBuffer` has been replaced by [struct@GLib.Bytes] and
+   [struct@GLib.ByteArray].
+ - `SoupDate` has been replaced by `GDateTime`.
+ - `SoupSession:ssl-strict` has been removed in favor of using the
+   [signal@Message::accept-certificate] signal.
+ - `soup_session_cancel_message()` has been removed instead you
+   pass a [class@Gio.Cancellable] to APIs and call [method@Gio.Cancellable.cancel].
+
+## Moved authenticate signal
+
+The `SoupSession::authenticate` signal has been replaced by
+[signal@Message::authenticate]. It now allows returning `TRUE` to signify if
+you will handle authentication which allows for asynchronous handling.
+
+## Structs are private
+
+You can no longer directly access various structs such as [class@Message]. These are
+now accessed by getters and setters. See below for direct
+conversions:
+
+<!-- TODO add links -->
+<table>
+    <tr>
+        <th>Struct field</th>
+        <th>Getter/Setter function</th>
+    </tr>
+    <tr>
+        <td>SoupMessage.method</td>
+        <td>soup_message_get_method()</td>
+    </tr>
+    <tr>
+        <td>SoupMessage.status_code</td>
+        <td>soup_message_get_status()</td>
+    </tr>
+    <tr>
+        <td>SoupMessage.reason_phrase</td>
+        <td>soup_message_get_reason_phrase()</td>
+    </tr>
+    <tr>
+        <td>SoupMessage.uri</td>
+        <td>soup_message_get_uri(), soup_message_set_uri()</td>
+    </tr>
+    <tr>
+        <td>SoupMessage.request_headers</td>
+        <td>soup_message_get_request_headers()</td>
+    </tr>
+    <tr>
+        <td>SoupMessage.response_headers</td>
+        <td>soup_message_get_response_headers()</td>
+    </tr>
+    <tr>
+        <td>SoupMessage.request_body</td>
+        <td>soup_message_set_request_body(), soup_message_set_request_body_from_bytes()</td>
+    </tr>
+    <tr>
+        <td>SoupMessage.response_body</td>
+        <td>See section on IO</td>
+    </tr>
+</table>
+
+Similar struct changes exist for [struct@Cookie] but have very straightforward
+replacements.
+
+## URI type changed
+
+The `SoupURI` type has been replaced with the [struct@GLib.Uri] type which has
+some implications.
+
+Creating a [struct@GLib.Uri] is generally as simple as `g_uri_parse (uri,
+ SOUP_HTTP_URI_FLAGS, NULL)`. You may want to add
+
+`G_URI_FLAGS_PARSE_RELAXED` to accept input that used to be considered valid.
+
+Note that unlike `SoupURI`, `GUri` is an immutable type so you cannot change the
+contents of one after it has been constructed. We provide [func@uri_copy] to aid
+in modifying them.
+
+The equivalent behavior to `soup_uri_to_string (uri, FALSE)`
+is `g_uri_to_string_partial (uri, G_URI_HIDE_PASSWORD)`.
+
+Since `GUri` does not provide any function to check for equality
+[func@uri_equal] still exists.
+
+Sending a `OPTIONS` message with a path of `*` is no longer a valid URI and has
+been replaced with [property@Message:is-options-ping].
+
+## Status codes no longer used for internal errors
+
+Previously [enum@Status] was used to hold libsoup errors
+(`SOUP_STATUS_IS_TRANSPORT_ERROR()`). Now all of these errors are propagated up
+through the normal [struct@GLib.Error] method on the various APIs to send
+messages. Here is a mapping chart between the status codes and new errors:
+
+<table>
+    <tr>
+        <th>Old Status Codes</th>
+        <th>New <code>GError</code></th>
+    </tr>
+    <tr>
+        <td><code>SOUP_STATUS_CANCELLED</code></td>
+        <td><code>G_IO_ERROR_CANCELLED</code></td>
+    </tr>
+    <tr>
+        <td><code>SOUP_STATUS_MALFORMED</code></td>
+        <td><code>SOUP_SESSION_ERROR_PARSING</code>, <code>SOUP_SESSION_ERROR_ENCODING</code></td>
+    </tr>
+    <tr>
+        <td><code>SOUP_STATUS_TOO_MANY_REDIRECTS</code></td>
+        <td><code>SOUP_SESSION_ERROR_TOO_MANY_REDIRECTS</code></td>
+    </tr>
+</table>
+
+## All IO is now GIOStream-based
+
+Previously there were ways to allow libsoup to read data into buffers and for
+you to read from those buffers such as `SoupMessage:response-body`
+`SoupMessage:response-body-data`, and `SoupServerMessage::got-chunk`.
+
+libsoup no longer stores a buffer of data for you to read from and instead it
+returns a [class@Gio.InputStream] which you read from using normal GIO APIs.
+
+If you want to simply request a buffer and nothing more you can use the
+[method@Session.send_and_read] or [method@Session.send_and_read_async] APIs.
+
+This also applies to writing data where you can set a [class@Gio.InputStream]
+using [method@Message.set_request_body] or use the convenience API
+[method@Message.set_request_body_from_bytes] to use a [struct@GLib.Bytes]
+buffer.
+
+## Clarification on thread-safety
+
+In libsoup 2 there was an attempt at making various APIs of the library
+thread-safe. However this was never well tested, maintained, or documented.
+
+In libsoup 3 it now behaves in line with other GObject libraries. Once you
+create a [class@Session] all usage of that session must happen on the same
+thread. You may create separate sessions per thread but in most use-cases you
+should be using the async APIs which handle non-blocking IO for you.
diff --git a/docs/reference/migrating-from-libsoup-2.xml b/docs/reference/migrating-from-libsoup-2.xml
deleted file mode 100644
index 084c0780..00000000
--- a/docs/reference/migrating-from-libsoup-2.xml
+++ /dev/null
@@ -1,192 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="http://docbook.org/xml/5.1/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
-<?xml-model href="http://docbook.org/xml/5.1/sch/docbook.sch" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>
-<chapter xmlns="http://docbook.org/ns/docbook"
-    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.1">
-   <title>Migrating from libsoup 2</title>
-    <sect2>
-        <title>Removed APIs</title>
-        <para>This is a list of APIs that have been removed:<itemizedlist>
-                <listitem>
-                    <para>XML-RPC support</para>
-                </listitem>
-                <listitem>
-                    <para>Handling of <literal>file://</literal> and <literal>data://</literal>
-                        URIs</para>
-                    <para>You should use <link
-linkend="GFile"><type>GFile</type></link> for the former and <link
-linkend="soup-uri-decode-data-uri"><function>soup_uri_decode_data_uri()</function></link> for the
-                        latter.</para>
-                </listitem>
-                <listitem>
-                    <para>Define aliases for property names</para>
-                    <para>You must use the string name of properties directly which works in libsoup
-                        2 already.</para>
-                </listitem>
-                <listitem>
-                    <para><literal>SoupSession:add-feature</literal> and <literal>SoupSession:add-feature-by-type</literal></para>
-                    <para>You must call <link linkend="soup-session-add-feature"><function>soup_session_add_feature()</function></link> and
-                        <link linkend="soup-session-add-feature-by-type"><function>soup_session_add_feature_by_type()</function></link> directly.</para>
-                </listitem>
-                <listitem>
-                    <para><type>SoupRequest</type></para>
-                    <para>You should use <link linkend="soup-session-send"><function>soup_session_send()</function></link> or
-                        <link linkend="soup-session-send-async"><function>soup_session_send_async()</function></link> methods.</para>
-                </listitem>
-                <listitem>
-                    <para><type>SoupAddress</type> has been replaced with <link linkend="GInetAddress"><type>GInetAddress</type></link>
-                        and <link linkend="GNetworkAddress"><type>GNetworkAddress</type></link></para>
-                </listitem>
-                <listitem>
-                    <para><type>SoupSocket</type> has been removed</para>
-                </listitem>
-                <listitem>
-                    <para><type>SoupProxyResolverDefault</type> is replaced by
-                        <link linkend="g-proxy-resolver-get-default"><function>g_proxy_resolver_get_default()</function></link></para>
-                </listitem>
-                <listitem>
-                    <para><type>SoupBuffer</type> has been replaced by <link linkend="GBytes"><type>GBytes</type></link> and <link linkend="GByteArray"><type>GByteArray</type></link></para>
-                </listitem>
-                <listitem>
-                    <para><type>SoupDate</type> has been replaced by <link linkend="GDateTime"><type>GDateTime</type></link></para>
-                </listitem>
-                <listitem>
-                    <para><literal>SoupSession:ssl-strict</literal> has been removed in favor of using the <link linkend="SoupMessage-accept-certificate"><literal>SoupMessage:accept-certificate</literal></link> signal.</para>
-                </listitem>
-                <listitem>
-                    <para><literal>soup_session_cancel_message()</literal> has been removed</para>
-                    <para>Instead you pass a <link linkend="GCancellable"><type>GCancellable</type></link> to APIs and call <link linkend="g_cancellable_cancel"><function>g_cancellable_cancel()</function></link>.</para>
-                </listitem>
-            </itemizedlist></para>
-    </sect2>
-  <sect2>
-    <title>Moved authenticate signal</title>
-        <para>The <literal>SoupSession::authenticate</literal> signal has been replaced by
-            <link linkend="SoupMessage-authenticate"><literal>SoupMessage::authenticate</literal></link>. It now allows returning <literal>TRUE</literal> to signifiy
-            if you will handle authentication which allows for asynchronous handling.</para>
-  </sect2>
-  <sect2>
-        <title>Structs are private</title>
-        <para>You can no longer directly access various structs such as SoupMessage. These are now
-            accessed by getters and setters. See below for direct conversions:<informaltable>
-                <tgroup cols="2">
-                    <colspec colname="c1" colnum="1" colwidth="1*"/>
-                    <colspec colname="c2" colnum="2" colwidth="1*"/>
-                    <thead>
-                        <row>
-                            <entry>Struct field</entry>
-                            <entry>Getter/Setter function</entry>
-                        </row>
-                    </thead>
-                    <tbody>
-                        <row>
-                            <entry>SoupMessage.method</entry>
-                            <entry><link linkend="soup-message-get-method"><function>soup_message_get_method()</function></link></entry>
-                        </row>
-                        <row>
-                            <entry>SoupMessage.status_code</entry>
-                            <entry><link linkend="soup-message-get-status"><function>soup_message_get_status()</function></link></entry>
-                        </row>
-                        <row>
-                            <entry>SoupMessage.reason_phrase</entry>
-                            <entry><link linkend="soup-message-get-reason-phrase"><function>soup_message_get_reason_phrase()</function></link></entry>
-                        </row>
-                        <row>
-                            <entry>SoupMessage.uri</entry>
-                            <entry><link linkend="soup-message-get-uri"><function>soup_message_get_uri()</function></link>, <link linkend="soup-message-set-uri"><function>soup_message_set_uri()</function></link></entry>
-                        </row>
-                        <row>
-                            <entry>SoupMessage.request_headers</entry>
-                            <entry><link linkend="soup-message-get-request-headers"><function>soup_message_get_request_headers()</function></link></entry>
-                        </row>
-                        <row>
-                            <entry>SoupMessage.response_headers</entry>
-                            <entry><link linkend="soup-message-get-response-headers"><function>soup_message_get_response_headers()</function></link></entry>
-                        </row>
-                        <row>
-                            <entry>SoupMessage.request_body</entry>
-                            <entry><link linkend="soup-message-set-request-body"><function>soup_message_set_request_body()</function></link>,
-                                <link linkend="soup-message-set-request-body-from-bytes"><function>soup_message_set_request_body_from_bytes()</function></link></entry>
-                        </row>
-                        <row>
-                            <entry>SoupMessage.response_body</entry>
-                            <entry>See <link linkend="io-stream-based">section on IO</link> </entry>
-                        </row>
-                    </tbody>
-                </tgroup>
-            </informaltable></para>
-        <para>Similar struct changes exist for <link linkend="SoupCookie"><type>SoupCookie</type></link> but have very straightforward
-            replacements.</para>
-    </sect2>
-    <sect2>
-        <title>URI type changed</title>
-        <para>The <type>SoupURI</type> type has been replaced with the <link linkend="GUri"><type>GUri</type></link> type which has some
-            implications.</para>
-        <para>Creating a <link linkend="GUri"><type>GUri</type></link> is generally as simple as <code>g_uri_parse (uri,
-                SOUP_HTTP_URI_FLAGS, NULL)</code>. You may want to add
-                <literal>G_URI_FLAGS_PARSE_RELAXED</literal> to accept input that used to be
-            considered valid.</para>
-        <para>Note that unlike <type>SoupURI</type> <link linkend="GUri"><type>GUri</type></link> is an immutable type so you cannot change the contents
-            of one after it has been constructed. We provide <link linkend="soup_copy_uri"><function>soup_copy_uri()</function></link> to aid in modifying them.</para>
-        <para>The equivalent behavior to <code>soup_uri_to_string (uri, FALSE)</code> is
-                <code>g_uri_to_string_partial (uri, G_URI_HIDE_PASSWORD)</code>.</para>
-        <para>Since GUri does not provide any function to check for equality
-                <link linkend="soup_uri_equal"><function>soup_uri_equal()</function></link> still exists.</para>
-        <para>Sending a <literal>OPTIONS</literal> message with a path of <literal>*</literal> is no
-            longer a valid URI and has been replaced with SoupMessage:options-ping.</para>
-    </sect2>
-    <sect2>
-        <title>Status codes no longer used for internal errors</title>
-        <para>Previously <link linkend="SoupStatus"><type>SoupStatus</type></link> was used to hold libsoup errors
-                (<code>SOUP_STATUS_IS_TRANSPORT_ERROR()</code>). Now all of these errors are
-            propagated up through the normal <link linkend="GError"><type>GError</type></link> method on the various APIs to send messages.
-            Here is a mapping chart between the status codes and new errors:<informaltable>
-                <tgroup cols="2">
-                    <colspec colname="c1" colnum="1" colwidth="1*"/>
-                    <colspec colname="newCol4" colnum="2" colwidth="1*"/>
-                    <thead>
-                        <row>
-                            <entry>Old Status Codes</entry>
-                            <entry>New GError</entry>
-                        </row>
-                    </thead>
-                    <tbody>
-                        <row>
-                            <entry><code>SOUP_STATUS_CANCELLED</code></entry>
-                            <entry><link linkend="G-IO-ERROR-CANCELLED:CAPS"><code>G_IO_ERROR_CANCELLED</code></link></entry>
-                        </row>
-                        <row>
-                            <entry><code>SOUP_STATUS_MALFORMED</code></entry>
-                            <entry><link linkend="SOUP-SESSION-ERROR-PARSING:CAPS"><code>SOUP_SESSION_ERROR_PARSING</code></link>, <link linkend="SOUP-SESSION-ERROR-ENCODING:CAPS"><code>SOUP_SESSION_ERROR_ENCODING</code></link></entry>
-                        </row>
-                        <row>
-                            <entry><code>SOUP_STATUS_TOO_MANY_REDIRECTS</code></entry>
-                            <entry><link linkend="SOUP-SESSION-ERROR-TOO-MANY-REDIRECTS:CAPS"><code>SOUP_SESSION_ERROR_TOO_MANY_REDIRECTS</code></link></entry>
-                        </row>
-                    </tbody>
-                </tgroup>
-            </informaltable></para>
-    </sect2>
-    <sect2 id="io-stream-based">
-        <title>All IO is now GIOStream-based</title>
-        <para>Previously there were ways to allow libsoup to read data into buffers and for you to
-            read from those buffers such as <literal>SoupMessage:response-body</literal>,
-            <literal>SoupMessage:response-body-data</literal>, and <literal>SoupMessage::got-chunk</literal>.</para>
-        <para>libsoup no longer stores a buffer of data for you to read from and instead it returns
-            a <link linkend="GInputStream"><type>GInputStream</type></link> which you read from using normal GIO APIs.</para>
-        <para>If you want to simply request a buffer and nothing more you can use the
-                <link linkend="soup_session_send_and_read"><function>soup_session_send_and_read()</function></link> or
-                <link linkend="soup_session_send_and_read_async"><function>soup_session_send_and_read_async()</function></link> APIs.</para>
-        <para>This also applies to writing data where you can set a <link linkend="GInputStream"><type>GInputStream</type></link> using
-                <link linkend="soup_message_set_request_body"><function>soup_message_set_request_body()</function></link> or use the convenience API
-                <link linkend="soup_message_set_request_body_from_bytes"><function>soup_message_set_request_body_from_bytes()</function></link> to use a GBytes
-            buffer.</para>
-    </sect2>
-    <sect2 id="threading">
-        <title>Clarification on thread-safety</title>
-        <para>In libsoup 2 there was an attempt at making various APIs of the library thread-safe. However this was never well tested, maintained, or documented.</para>
-        <para>In libsoup 3 it now behaves in line with other GObject libraries. Once you create a <link linkend="SoupSession"><type>SoupSession</type></link> all usage of that
-            session must happen on the same thread. You may create seperate sessions per thread but in most use-cases you should be using the async APIs which handle non-blocking IO for you.</para>
-    </sect2>
-</chapter>
-
diff --git a/docs/reference/server-howto.md b/docs/reference/server-howto.md
new file mode 100644
index 00000000..cb1beb8d
--- /dev/null
+++ b/docs/reference/server-howto.md
@@ -0,0 +1,247 @@
+Title: Server Basics
+Slug: server-howto
+
+# Server Basics
+
+## Creating a SoupServer
+
+As with the client API, there is a single object that will encapsulate
+most of your interactions with libsoup. In this case, [class@Server].
+
+You create the server with [ctor@Server.new], and as with the [class@Session]
+constructor, you can specify a few additional options:
+
+<table>
+    <tr>
+        <td>[property@Server:tls-certificate]</td>
+        <td>
+            A [class@Gio.TlsCertificate]
+            (containing a private key) that will be used when handling
+            HTTPS requests on the server.
+        </td>
+    </tr>
+    <tr>
+        <td>[property@Server:raw-paths]</literal></td>
+        <td>
+            Set this to <tt>TRUE</tt> if you don't want
+            libsoup to decode %-encoding
+            in the Request-URI. (e.g. because you need to treat
+            <tt>"/foo/bar"</tt> and
+            <tt>"/foo%2Fbar"</tt> as different paths.
+    </td>
+    </tr>
+    <tr>
+        <td>[property@Server:server-header]</td>
+        <td>
+            Allows you to set a Server header string that will be sent
+            on all responses.
+        </td>
+    </tr>
+</table>
+
+## Adding Listening Sockets
+
+To tell the server where to listen, call [method@Server.listen] (to listen on a
+specific [class@Gio.SocketAddress]), [method@Server.listen_all] (to listen on a
+given port on all network interfaces), or [method@Server.listen_local] (to
+listen to a given port on the `loopback` interface only). You can call any of
+these functions multiple times, to set up multiple listening sockets.
+
+To set up an HTTPS server, you must first either set the
+[property@Server:tls-certificate] property, or else call
+[method@Server.set_tls_certificate]. After that you can pass the
+`SOUP_SERVER_LISTEN_HTTPS` option to [method@Server.listen], etc.
+
+By default, servers listen for both IPv4 and IPv6 connections; if you don't want
+this, use the `SOUP_SERVER_LISTEN_IPV4_ONLY` or `SOUP_SERVER_LISTEN_IPV6_ONLY`
+options.
+
+The server runs asynchronously, in the thread-default [struct@GLib.MainContext]
+of the thread in which the `listen` calls were made.
+
+## Adding Handlers
+
+By default, [class@Server] returns "404 Not Found" in response to all requests
+(except ones that it can't parse, which get "400 Bad Request"). To override this
+behavior, call [class@Server.add_handler] to set a callback to handle certain
+URI paths.
+
+```c
+soup_server_add_handler (server, "/foo", server_callback,
+                         data, destroy_notify);
+```
+
+The `"/foo"` indicates the base path for this handler. When a request comes in,
+if there is a handler registered for exactly the path in the request's
+`Request-URI`, then that handler will be called. Otherwise libsoup will strip
+path components one by one until it finds a matching handler. So for example, a
+request of the form `GET /foo/bar/baz.html?a=1&b=2 HTTP/1.1` would look for
+handlers for `/foo/bar/baz.html`, `/foo/bar`, and `/foo`. If a handler has been
+registered with a `NULL` base path, then it is used as the default handler for
+any request that doesn't match any other handler.
+
+## Responding to Requests
+
+A handler callback looks something like this:
+
+```c
+static void
+server_callback (SoupServer        *server,
+                 SoupServerMessage *msg, 
+                 const char        *path,
+                 GHashTable        *query,
+                 gpointer           user_data)
+{
+    // ...
+}
+```
+
+`msg` is the request that has been received and `user_data` is the data that was
+passed to [method@Server.add_handler]. `path` is the path (from `msg`'s URI),
+and `query` contains the result of parsing the URI query field. (It is `NULL` if
+there was no query.)
+
+By default, libsoup assumes that you have completely finished processing the
+message when you return from the callback, and that it can therefore begin
+sending the response. If you are not ready to send a response immediately (e.g.
+you have to contact another server, or wait for data from a database), you must
+call [method@Server.pause_message] on the message before returning from the
+callback. This will delay sending a response until you call
+[method@Server.unpause_message]. (You must also connect to the
+[signal@ServerMessage::finished] signal on the message in this case, so that you
+can break off processing if the client unexpectedly disconnects before you start
+sending the data.)
+
+To set the response status, call [method@ServerMessage.set_status]. If the
+response requires a body, you must decide whether to use `Content-Length`
+encoding (the default), or `chunked` encoding.
+
+## Responding with `Content-Length` Encoding
+
+This is the simpler way to set a response body, if you have all of the data
+available at once.
+
+```c
+static void
+server_callback (SoupServer        *server,
+                 SoupServerMessage *msg, 
+                 const char        *path,
+                 GHashTable        *query,
+                 gpointer           user_data)
+{
+    MyServerData *server_data = user_data;
+    const char *mime_type;
+    GByteArray *body;
+
+    if (soup_server_message_get_method (msg) != SOUP_METHOD_GET) {
+        soup_server_message_set_status (msg, SOUP_STATUS_NOT_IMPLEMENTED, NULL);
+        return;
+    }
+
+    /* This is somewhat silly. Presumably your server will do
+     * something more interesting.
+     */
+    body = g_hash_table_lookup (server_data->bodies, path);
+    mime_type = g_hash_table_lookup (server_data->mime_types, path);
+    if (!body || !mime_type) {
+        soup_server_message_set_status (msg, SOUP_STATUS_NOT_FOUND, NULL);
+        return;
+    }
+
+    soup_server_message_set_status (msg, SOUP_STATUS_OK, NULL);
+    soup_server_message_set_response (msg, mime_type, SOUP_MEMORY_COPY,
+                                      body->data, body->len);
+}
+```
+
+# Responding with `chunked` Encoding
+
+If you want to supply the response body in chunks as it becomes available, use
+`chunked` encoding instead. In this case, first call
+`soup_message_headers_set_encoding (msg->response_headers,
+SOUP_ENCODING_CHUNKED)` to tell libsoup that you'll be using `chunked` encoding.
+Then call [method@MessageBody.append] (or [method@MessageBody.append_bytes]) on
+`msg->response_body` with each chunk of the response body as it becomes
+available, and call [method@MessageBody.complete] when the response is complete.
+After each of these calls, you must also call [class@Server.unpause_message] to
+cause the chunk to be sent. (You do not normally need to call
+[method@Server.pause_message], because I/O is automatically paused when doing a
+`chunked` transfer if no chunks are available.)
+
+When using chunked encoding, you must also connect to the
+[signal@ServerMessage::finished] signal on the message, so that you will be
+notified if the client disconnects between two chunks; [class@Server] will unref
+the message if that happens, so you must stop adding new chunks to the response
+at that point. (An alternate possibility is to write each new chunk only when
+the [signal@ServerMessage::wrote_chunk] signal is emitted indicating that the
+previous one was written successfully.)
+
+The **`simple-proxy`** example in the `examples/` directory gives an example of
+using `chunked` encoding.
+
+## Handling Authentication
+
+To have [class@Server] handle HTTP authentication for you, create a
+[class@AuthDomainBasic] or [class@AuthDomainDigest], and pass it to
+[method@Server.add_auth_domain]:
+
+```c
+SoupAuthDomain *domain;
+
+domain = soup_auth_domain_basic_new (
+    "realm", "My Realm",
+    "auth-callback", auth_callback,
+    "auth-data", auth_data,
+    "add-path", "/foo",
+    "add-path", "/bar/private",
+    NULL);
+soup_server_add_auth_domain (server, domain);
+g_object_unref (domain);
+```
+
+Then, every request under one of the auth domain's paths will be passed to the
+`auth_callback` first before being passed to the `server_callback`:
+
+```c
+static gboolean
+auth_callback (SoupAuthDomain *domain, SoupServerMessage *msg,
+               const char *username, const char *password,
+               gpointer user_data)
+{
+    MyServerData *server_data = user_data;
+    MyUserData *user;
+
+    user = my_server_data_lookup_user (server_data, username);
+    if (!user)
+        return FALSE;
+
+    /* FIXME: Don't do this. Keeping a cleartext password database
+     * is bad.
+     */
+    return strcmp (password, user->password) == 0;
+}
+```
+
+
+The [callback@AuthDomainBasicAuthCallback] is given the username and password
+from the `Authorization` header and must determine, in some server-specific
+manner, whether or not to accept them. (In this example we compare the password
+against a cleartext password database, but it would be better to store the
+password somehow encoded, as in the UNIX password database. Alternatively, you
+may need to delegate the password check to PAM or some other service.)
+
+If you are using Digest authentication, note that
+[callback@AuthDomainDigestAuthCallback] works completely differently (since the
+server doesn't receive the cleartext password from the client in that case, so
+there's no way to compare it directly). See the documentation for
+[class@AuthDomainDigest] for more details.
+
+You can have multiple [class@AuthDomain]s attached to a [class@Server], either
+in separate parts of the path hierarchy, or overlapping. (e.g. you might want to
+accept either Basic or Digest authentication for a given path.) When more than
+one auth domain covers a given path, the request will be accepted if the user
+authenticates successfully against *any* of the domains.
+
+If you want to require authentication for some requests under a certain path,
+but not all of them (e.g. you want to authenticate `PUT` requests, but not `GET`
+requests), use a [callback@AuthDomainFilter].
diff --git a/docs/reference/server-howto.xml b/docs/reference/server-howto.xml
deleted file mode 100644
index 7f743e4f..00000000
--- a/docs/reference/server-howto.xml
+++ /dev/null
@@ -1,380 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
-               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
-<refentry id="libsoup-server-howto">
-<refmeta>
-<refentrytitle>Server Basics</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>LIBSOUP Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>libsoup Server Basics</refname>
-</refnamediv>
-
-<refsect2>
-<title>Creating a SoupServer</title>
-
-<para>
-As with the client API, there is a single object that will encapsulate
-most of your interactions with libsoup. In this case, <link
-linkend="SoupServer"><type>SoupServer</type></link>.
-</para>
-
-<para>
-You create the server with <link
-linkend="soup-server-new"><function>soup_server_new</function></link>,
-and as with the <type>SoupSession</type> constructor, you can specify
-a few additional options:
-</para>
-
-<variablelist>
-    <varlistentry>
-	<term><link linkend="SoupServer:tls-certificate"><literal>"tls-certificate"</literal></link></term>
-	<listitem><para>
-	    A <link
-	    linkend="GTlsCertificate"><type>GTlsCertificate</type></link>
-	    (containing a private key) that will be used when handling
-	    HTTPS requests on the server.
-	</para></listitem>
-    </varlistentry>
-    <varlistentry>
-	<term><link linkend="SoupServer:raw-paths"><literal>"raw-paths"</literal></link></term>
-	<listitem><para>
-	    Set this to <literal>TRUE</literal> if you don't want
-	    <application>libsoup</application> to decode %-encoding
-	    in the Request-URI. (Eg, because you need to treat
-	    <literal>"/foo/bar"</literal> and
-	    <literal>"/foo%2Fbar"</literal> as different paths.
-	</para></listitem>
-    </varlistentry>
-    <varlistentry>
-	<term><link linkend="SoupServer:server-header"><literal>"server-header"</literal></link></term>
-	<listitem><para>
-	    Allows you to set a Server header string that will be sent
-	    on all responses.
-	</para></listitem>
-    </varlistentry>
-</variablelist>
-
-</refsect2>
-
-<refsect2>
-<title>Adding Listening Sockets</title>
-
-<para>
-  To tell the server where to listen, call <link
-  linkend="soup-server-listen"><function>soup_server_listen</function></link>
-  (to listen on a specific <link
-  linkend="GSocketAddress"><type>GSocketAddress</type></link>), <link
-  linkend="soup-server-listen-all"><function>soup_server_listen_all</function></link>
-  (to listen on a given port on all network interfaces), or <link
-  linkend="soup-server-listen-local"><function>soup_server_listen_local</function></link>
-  (to listen to a given port on the loopback interface only). You can
-  call any of these functions multiple times, to set up multiple
-  listening sockets.
-</para>
-
-<para>
-  To set up an HTTPS server, you must first either set the <link
-  linkend="SoupServer:tls-certificate"><literal>SoupServer:tls-certificate</literal></link>
-  property, or else call <link
-  linkend="soup-server-set-ssl-cert-file"><function>soup_server_set_ssl_cert_file</function></link>.
-  After that you can pass the <link
-  linkend="SOUP-SERVER-LISTEN-HTTPS:CAPS"><literal>SOUP_SERVER_LISTEN_HTTPS</literal></link>
-  option to <link
-  linkend="soup-server-listen"><function>soup_server_listen</function></link>,
-  etc.
-</para>
-
-<para>
-  By default, servers listen for both IPv4 and IPv6 connections; if
-  you don't want this, use the <link
-  linkend="SOUP-SERVER-LISTEN-IPV4-ONLY:CAPS"><literal>SOUP_SERVER_LISTEN_IPV4_ONLY</literal></link>
-  or <link
-  linkend="SOUP-SERVER-LISTEN-IPV6-ONLY:CAPS"><literal>SOUP_SERVER_LISTEN_IPV6_ONLY</literal></link>
-  options.
-</para>
-
-<para>
-  The server runs asynchronously, in the thread-default
-  <link linkend="GMainContext"><type>GMainContext</type></link> of the
-  thread in which the "listen" calls were made.
-</para>
-</refsect2>
-
-<refsect2>
-<title>Adding Handlers</title>
-
-<para>
-By default, <link linkend="SoupServer"><type>SoupServer</type></link>
-returns "404 Not Found" in response to all requests (except ones that
-it can't parse, which get "400 Bad Request"). To override this
-behavior, call <link
-linkend="soup-server-add-handler"><function>soup_server_add_handler</function></link>
-to set a callback to handle certain URI paths.
-</para>
-
-<informalexample><programlisting>
-	soup_server_add_handler (server, "/foo", server_callback,
-	                         data, destroy_notify);
-</programlisting></informalexample>
-
-<para>
-The <literal>"/foo"</literal> indicates the base path for this
-handler. When a request comes in, if there is a handler registered for
-exactly the path in the request's <literal>Request-URI</literal>, then
-that handler will be called. Otherwise
-<application>libsoup</application> will strip path components one by
-one until it finds a matching handler. So for example, a request of
-the form
-"<literal>GET&#xA0;/foo/bar/baz.html?a=1&amp;b=2&#xA0;HTTP/1.1</literal>"
-would look for handlers for "<literal>/foo/bar/baz.html</literal>",
-"<literal>/foo/bar</literal>", and "<literal>/foo</literal>". If a
-handler has been registered with a <literal>NULL</literal> base path,
-then it is used as the default handler for any request that doesn't
-match any other handler.
-</para>
-
-</refsect2>
-
-<refsect2>
-<title>Responding to Requests</title>
-
-<para>
-A handler callback looks something like this:
-</para>
-
-<informalexample><programlisting>
-static void
-server_callback (SoupServer        *server,
-                 SoupServerMessage *msg, 
-                 const char        *path,
-                 GHashTable        *query,
-                 gpointer           user_data)
-{
-	...
-}
-</programlisting></informalexample>
-
-<para>
-<literal>msg</literal> is the request that has been received and
-<literal>user_data</literal> is the data that was passed to <link
-linkend="soup-server-add-handler"><function>soup_server_add_handler</function></link>.
-<literal>path</literal> is the path (from <literal>msg</literal>'s
-URI), and <literal>query</literal> contains the result of parsing the
-URI query field. (It is <literal>NULL</literal> if there was no
-query.)
-</para>
-
-<para>
-By default, <application>libsoup</application> assumes that you have
-completely finished processing the message when you return from the
-callback, and that it can therefore begin sending the response. If you
-are not ready to send a response immediately (eg, you have to contact
-another server, or wait for data from a database), you must call <link
-linkend="soup-server-pause-message"><function>soup_server_pause_message</function></link>
-on the message before returning from the callback. This will delay
-sending a response until you call <link
-linkend="soup-server-unpause-message"><function>soup_server_unpause_message</function></link>.
-(You must also connect to the <link
-linkend="SoupServerMessage-finished">finished</link> signal on the message
-in this case, so that you can break off processing if the client
-unexpectedly disconnects before you start sending the data.)
-</para>
-
-<para>
-To set the response status, call <link
-linkend="soup-server-message-set-status"><function>soup_server_message_set_status</function></link>.
-If the response requires a body, you must decide whether to use
-<literal>Content-Length</literal> encoding (the default), or
-<literal>chunked</literal> encoding.
-</para>
-
-<refsect3>
-<title>Responding with <literal>Content-Length</literal>
-Encoding</title>
-
-<para>
-This is the simpler way to set a response body, if you have all of the
-data available at once.
-</para>
-
-<informalexample><programlisting>
-static void
-server_callback (SoupServer        *server,
-                 SoupServerMessage *msg, 
-                 const char        *path,
-                 GHashTable        *query,
-                 gpointer           user_data)
-{
-	MyServerData *server_data = user_data;
-	const char *mime_type;
-	GByteArray *body;
-
-	if (soup_server_message_get_method (msg) != SOUP_METHOD_GET) {
-		soup_server_message_set_status (msg, SOUP_STATUS_NOT_IMPLEMENTED, NULL);
-		return;
-	}
-
-	/* This is somewhat silly. Presumably your server will do
-	 * something more interesting.
-	 */
-	body = g_hash_table_lookup (server_data->bodies, path);
-	mime_type = g_hash_table_lookup (server_data->mime_types, path);
-	if (!body || !mime_type) {
-		soup_server_message_set_status (msg, SOUP_STATUS_NOT_FOUND, NULL);
-		return;
-	}
-
-	soup_server_message_set_status (msg, SOUP_STATUS_OK, NULL);
-	soup_server_message_set_response (msg, mime_type, SOUP_MEMORY_COPY,
-	                                  body->data, body->len);
-}
-</programlisting></informalexample>
-
-</refsect3>
-
-<refsect3>
-<title>Responding with <literal>chunked</literal> Encoding</title>
-
-<para>
-If you want to supply the response body in chunks as it becomes
-available, use <literal>chunked</literal> encoding instead. In this
-case, first call <link
-linkend="soup-message-headers-set-encoding"><function>soup_message_headers_set_encoding</function></link>&#160;<literal>(msg->response_headers,&#160;<link
-linkend="SoupEncoding">SOUP_ENCODING_CHUNKED</link>)</literal>
-to tell <application>libsoup</application> that you'll be using
-chunked encoding. Then call <link
-linkend="soup-message-body-append"><function>soup_message_body_append</function></link>
-(or <link
-linkend="soup-message-body-append-bytes"><function>soup_message_body_append_bytes</function></link>)
-on <literal>msg->response_body</literal> with each chunk of the
-response body as it becomes available, and call <link
-linkend="soup-message-body-complete"><function>soup_message_body_complete</function></link>
-when the response is complete. After each of these calls, you must
-also call <link
-linkend="soup-server-unpause-message"><function>soup_server_unpause_message</function></link>
-to cause the chunk to be sent. (You do not normally need to call <link
-linkend="soup-server-pause-message"><function>soup_server_pause_message</function></link>,
-because I/O is automatically paused when doing a
-<literal>chunked</literal> transfer if no chunks are available.)
-</para>
-
-<para>
-When using chunked encoding, you must also connect to the <link
-linkend="SoupServerMessage-finished">finished</link> signal on the message,
-so that you will be notified if the client disconnects between two
-chunks; <type>SoupServer</type> will unref the message if that
-happens, so you must stop adding new chunks to the response at that
-point. (An alternate possibility is to write each new chunk only when
-the <link linkend="SoupServerMessage-wrote-chunk">wrote_chunk</link> signal
-is emitted indicating that the previous one was written successfully.)
-</para>
-
-<para>
-The <emphasis role="bold"><literal>simple-proxy</literal></emphasis>
-example in the <literal>examples/</literal> directory gives an example of
-using <literal>chunked</literal> encoding.
-</para>
-
-</refsect3>
-</refsect2>
-
-
-<refsect2>
-<title>Handling Authentication</title>
-
-<para>
-To have <link linkend="SoupServer"><type>SoupServer</type></link>
-handle HTTP authentication for you, create a <link
-linkend="SoupAuthDomainBasic"><type>SoupAuthDomainBasic</type></link>
-or <link
-linkend="SoupAuthDomainDigest"><type>SoupAuthDomainDigest</type></link>,
-and pass it to <link
-linkend="soup-server-add-auth-domain"><function>soup_server_add_auth_domain</function></link>:
-</para>
-
-<informalexample><programlisting>
-	SoupAuthDomain *domain;
-
-	domain = soup_auth_domain_basic_new (
-		"realm", "My Realm",
-		"auth-callback", auth_callback,
-		"auth-data", auth_data,
-		"add-path", "/foo",
-		"add-path", "/bar/private",
-		NULL);
-	soup_server_add_auth_domain (server, domain);
-	g_object_unref (domain);
-</programlisting></informalexample>
-
-<para>
-Then, every request under one of the auth domain's paths will be
-passed to the <literal>auth_callback</literal> first before being
-passed to the <literal>server_callback</literal>:
-</para>
-
-<informalexample><programlisting>
-static gboolean
-auth_callback (SoupAuthDomain *domain, SoupServerMessage *msg,
-               const char *username, const char *password,
-               gpointer user_data)
-{
-	MyServerData *server_data = user_data;
-	MyUserData *user;
-
-	user = my_server_data_lookup_user (server_data, username);
-	if (!user)
-		return FALSE;
-
-	/* FIXME: Don't do this. Keeping a cleartext password database
-	 * is bad.
-	 */
-	return strcmp (password, user->password) == 0;
-}
-</programlisting></informalexample>
-
-<para>
-The <link
-linkend="SoupAuthDomainBasicAuthCallback"><type>SoupAuthDomainBasicAuthCallback</type></link>
-is given the username and password from the
-<literal>Authorization</literal> header and must determine, in some
-server-specific manner, whether or not to accept them. (In this
-example we compare the password against a cleartext password database,
-but it would be better to store the password somehow encoded, as in
-the UNIX password database. Alternatively, you may need to delegate
-the password check to PAM or some other service.)
-</para>
-
-<para>
-If you are using Digest authentication, note that <link
-linkend="SoupAuthDomainDigestAuthCallback"><type>SoupAuthDomainDigestAuthCallback</type></link>
-works completely differently (since the server doesn't receive the
-cleartext password from the client in that case, so there's no way to
-compare it directly). See the documentation for <link
-linkend="SoupAuthDomainDigest"><type>SoupAuthDomainDigest</type></link>
-for more details.
-</para>
-
-<para>
-You can have multiple <type>SoupAuthDomain</type>s attached to a
-<literal>SoupServer</literal>, either in separate parts of the path
-hierarchy, or overlapping. (Eg, you might want to accept either Basic
-or Digest authentication for a given path.) When more than one auth
-domain covers a given path, the request will be accepted if the user
-authenticates successfully against <emphasis>any</emphasis> of the
-domains.
-</para>
-
-<para>
-If you want to require authentication for some requests under a
-certain path, but not all of them (eg, you want to authenticate
-<literal>PUT</literal> requests, but not <literal>GET</literal>
-requests), use a <link
-linkend="SoupAuthDomainFilter"><type>SoupAuthDomainFilter</type></link>.
-</para>
-
-</refsect2>
-
-</refentry>
diff --git a/docs/reference/urlmap.js b/docs/reference/urlmap.js
new file mode 100644
index 00000000..67e8a251
--- /dev/null
+++ b/docs/reference/urlmap.js
@@ -0,0 +1,6 @@
+// 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/' ],
+]
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