diff --git a/doc/dbus/Makefile b/doc/dbus/Makefile
index 7195475146..435844c6bd 100644
--- a/doc/dbus/Makefile
+++ b/doc/dbus/Makefile
@@ -2,52 +2,15 @@ distdir=../dist/dbus
 tmpdir=./tmp
 
 # build HTML for GitHub pages
-all: ${distdir} ${tmpdir}
-	for f in org.opensuse.Agama*.doc.xml; do \
-	  echo $$f; \
-	  gdbus-codegen \
-	    --interface-prefix=org.opensuse.Agama. \
-	    --output-directory=${tmpdir} \
-	    --generate-docbook=ref \
-	    $$f; \
-	  docbook=${tmpdir}/ref-$${f%.doc.xml}.xml; \
-	  xmlto -o ${distdir} --skip-validation html-nochunks $$docbook; \
-	done
-	./make-index > index.html
-	cp index.html ${distdir}
+all:
+	./build-docs "${distdir}" "${tmpdir}"
 
-# 'foo 2> >(grep ... >&2)' greps stderr and keeps it as stderr
-NO_COMMENTS=xmlstarlet canonic --without-comments 2> >(grep -v 'Attempt to load network entity' >&2)
-# bash because of the >() process substitution
-SHELL=/bin/bash
+clean:
+	rm -rf "${distdir}" "${tmpdir}"
 
 # check that the implementation and documentation haven't diverged
-# TODO: factor out a script to decouple Make syntax from the rest
 diff: check
-check: ${tmpdir}
-	ALL_GOOD=true; \
-	for doc_xml in org.opensuse.Agama*.doc.xml; do \
-	  IFACE=$${doc_xml%.doc.xml}; \
-	  bus_xml=bus/$$IFACE.bus.xml; \
-	  doc_iface=${tmpdir}/$$IFACE.doc.iface.xml; \
-	  bus_iface=${tmpdir}/$$IFACE.bus.iface.xml; \
-	  \
-	  echo "Diffing $$IFACE"; \
-	  \
-	  $(NO_COMMENTS) \
-	    $${doc_xml} \
-	    > $${doc_iface}; \
-	  xmlstarlet ed \
-	    -d "//interface[@name!='$$IFACE']" \
-	    $${bus_xml} \
-	    | $(NO_COMMENTS) - \
-	    > $${bus_iface}; \
-	  diff --ignore-blank-lines --ignore-trailing-space -u $${doc_iface} $${bus_iface} || ALL_GOOD=false; \
-	done; \
-	$$ALL_GOOD
-	@echo "NO DIFF, YAY"
+check:
+	./compare-impl-and-docs "${tmpdir}"
 
-${distdir}:
-	mkdir -p $@
-${tmpdir}:
-	mkdir -p $@
+.PHONY: all diff check
\ No newline at end of file
diff --git a/doc/dbus/build-docs b/doc/dbus/build-docs
new file mode 100755
index 0000000000..0513a8ca21
--- /dev/null
+++ b/doc/dbus/build-docs
@@ -0,0 +1,36 @@
+#!/bin/sh
+# Build HTML for GitHub pages
+set -eu
+
+# Workflow:
+# gdbus-codegen (glib2-devel.rpm)
+# - reads *.doc.xml introspection with comments
+# - writes ref-*.xml, DocBook refentry pieces
+# xmlto
+# - reads  ref-*.xml
+# - writes *.html
+
+# TODO opt in for a repo-wide shellcheck
+
+# TODO help message
+distdir=$1
+tmpdir=$2
+mkdir -p "$distdir" "$tmpdir"
+
+for f in org.opensuse.Agama*.doc.xml; do
+  echo "$f"
+  gdbus-codegen \
+    --interface-prefix=org.opensuse.Agama. \
+    --output-directory="$tmpdir" \
+    --generate-docbook=ref \
+    "$f"
+  docbook="$tmpdir/ref-${f%.doc.xml}.xml"
+  xmlto \
+    -o "$distdir" \
+	--skip-validation \
+	--stringparam html.stylesheet=refentry-agama.css \
+	html-nochunks \
+	"$docbook"
+done
+./make-index > "$distdir"/index.html
+cp refentry-agama.css "$distdir"
diff --git a/doc/dbus/bus/README.md b/doc/dbus/bus/README.md
index 36328c2abe..47d3fbb0c1 100644
--- a/doc/dbus/bus/README.md
+++ b/doc/dbus/bus/README.md
@@ -4,6 +4,8 @@ exported by the Agama services.
 The files are produced by `seed.sh`.
 - FIXME: run it in CI.
 - FIXME: make it easy to run it *and* commit the result to git.
+  testing_using_container.sh,
+    (cd doc/dbus/bus; ./seed.sh)
 
 Each file name represents a D-Bus **interface** that we want to document.
 That is why some files have symlinks pointing to them (and why you see no
@@ -19,4 +21,4 @@ Run `make check`.
 
 FIXME: Storage1.ZFCP and Storage1.DASD needs an s390 machine to run,
 we should expose them on x86 too (returning errors), perhaps guarded by an
-`AGAMA_IGNORE_ARCH` flag?
+`AGAMA_MAINFRAME_COSPLAY` flag?
diff --git a/doc/dbus/bus/org.opensuse.Agama.Manager1.bus.xml b/doc/dbus/bus/org.opensuse.Agama.Manager1.bus.xml
index 945966dedd..805c7c39f7 100644
--- a/doc/dbus/bus/org.opensuse.Agama.Manager1.bus.xml
+++ b/doc/dbus/bus/org.opensuse.Agama.Manager1.bus.xml
@@ -35,7 +35,6 @@
       <arg name="result" direction="out" type="b"/>
     </method>
     <method name="CollectLogs">
-      <arg name="user" direction="in" type="s"/>
       <arg name="tarball_filesystem_path" direction="out" type="s"/>
     </method>
     <method name="Finish">
@@ -47,10 +46,16 @@
     <property type="b" name="IguanaBackend" access="read"/>
     <property type="as" name="BusyServices" access="read"/>
   </interface>
+  <interface name="org.opensuse.Agama1.LocaleMixin">
+    <method name="SetLocale">
+      <arg name="locale" direction="in" type="s"/>
+    </method>
+  </interface>
   <interface name="org.opensuse.Agama1.Progress">
     <property type="u" name="TotalSteps" access="read"/>
     <property type="(us)" name="CurrentStep" access="read"/>
     <property type="b" name="Finished" access="read"/>
+    <property type="as" name="Steps" access="read"/>
   </interface>
   <interface name="org.opensuse.Agama1.ServiceStatus">
     <property type="aa{sv}" name="All" access="read"/>
diff --git a/doc/dbus/bus/org.opensuse.Agama.Software1.bus.xml b/doc/dbus/bus/org.opensuse.Agama.Software1.bus.xml
index b2c21475f8..3ca7a2b966 100644
--- a/doc/dbus/bus/org.opensuse.Agama.Software1.bus.xml
+++ b/doc/dbus/bus/org.opensuse.Agama.Software1.bus.xml
@@ -29,6 +29,9 @@
     </signal>
   </interface>
   <interface name="org.opensuse.Agama.Software1">
+    <method name="ListRepositories">
+      <arg name="Result" direction="out" type="a(issssbb)"/>
+    </method>
     <method name="ListPatterns">
       <arg name="Filtered" direction="in" type="b"/>
       <arg name="Result" direction="out" type="a{s(sssss)}"/>
@@ -42,7 +45,8 @@
       <arg name="result" direction="out" type="b"/>
     </method>
     <method name="SetUserPatterns">
-      <arg name="ids" direction="in" type="as"/>
+      <arg name="add" direction="in" type="as"/>
+      <arg name="remove" direction="in" type="as"/>
       <arg name="wrong" direction="out" type="as"/>
     </method>
     <method name="ProvisionsSelected">
@@ -68,15 +72,23 @@
     </method>
     <method name="Finish">
     </method>
+    <signal name="ProbeFinished">
+    </signal>
     <property type="a{sy}" name="SelectedPatterns" access="read"/>
   </interface>
   <interface name="org.opensuse.Agama1.Issues">
-    <property type="a(ssuu)" name="All" access="read"/>
+    <property type="a(sssuu)" name="All" access="read"/>
+  </interface>
+  <interface name="org.opensuse.Agama1.LocaleMixin">
+    <method name="SetLocale">
+      <arg name="locale" direction="in" type="s"/>
+    </method>
   </interface>
   <interface name="org.opensuse.Agama1.Progress">
     <property type="u" name="TotalSteps" access="read"/>
     <property type="(us)" name="CurrentStep" access="read"/>
     <property type="b" name="Finished" access="read"/>
+    <property type="as" name="Steps" access="read"/>
   </interface>
   <interface name="org.opensuse.Agama1.ServiceStatus">
     <property type="aa{sv}" name="All" access="read"/>
diff --git a/doc/dbus/bus/org.opensuse.Agama.Storage1.bus.xml b/doc/dbus/bus/org.opensuse.Agama.Storage1.bus.xml
index 4e727c41cc..063fa00f54 100644
--- a/doc/dbus/bus/org.opensuse.Agama.Storage1.bus.xml
+++ b/doc/dbus/bus/org.opensuse.Agama.Storage1.bus.xml
@@ -1,12 +1,24 @@
-<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
-"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+<?xml version="1.0" encoding="UTF-8"?>
 <node name="/org/opensuse/Agama/Storage1">
-  <node name="ISCSI" />
-  <node name="iscsi_nodes" />
-  <node name="staging" />
-  <node name="system" />
-  <node name="zfcp_controllers" />
-  <node name="zfcp_disks" />
+  <node name="ISCSI"/>
+  <interface name="org.freedesktop.DBus.Introspectable">
+    <method name="Introspect">
+      <arg name="xml_data" direction="out" type="s"/>
+    </method>
+  </interface>
+  <interface name="org.freedesktop.DBus.ObjectManager">
+    <method name="GetManagedObjects">
+      <arg name="res" direction="out" type="a{oa{sa{sv}}}"/>
+    </method>
+    <signal name="InterfacesAdded">
+      <arg name="object" type="o"/>
+      <arg name="interfaces_and_properties" type="a{sa{sv}}"/>
+    </signal>
+    <signal name="InterfacesRemoved">
+      <arg name="object" type="o"/>
+      <arg name="interfaces" type="as"/>
+    </signal>
+  </interface>
   <interface name="org.freedesktop.DBus.Properties">
     <method name="Get">
       <arg name="interface_name" direction="in" type="s"/>
@@ -28,42 +40,6 @@
       <arg name="invalidated_properties" type="as"/>
     </signal>
   </interface>
-  <interface name="org.freedesktop.DBus.Introspectable">
-    <method name="Introspect">
-      <arg name="xml_data" direction="out" type="s"/>
-    </method>
-  </interface>
-  <interface name="org.freedesktop.DBus.ObjectManager">
-    <method name="GetManagedObjects">
-      <arg name="res" direction="out" type="a{oa{sa{sv}}}"/>
-    </method>
-    <signal name="InterfacesAdded">
-      <arg name="object" type="o"/>
-      <arg name="interfaces_and_properties" type="a{sa{sv}}"/>
-    </signal>
-    <signal name="InterfacesRemoved">
-      <arg name="object" type="o"/>
-      <arg name="interfaces" type="as"/>
-    </signal>
-  </interface>
-  <interface name="org.opensuse.Agama1.Issues">
-    <property type="a(sssuu)" name="All" access="read"/>
-  </interface>
-  <interface name="org.opensuse.Agama1.LocaleMixin">
-    <method name="SetLocale">
-      <arg name="locale" direction="in" type="s"/>
-    </method>
-  </interface>
-  <interface name="org.opensuse.Agama1.Progress">
-    <property type="u" name="TotalSteps" access="read"/>
-    <property type="(us)" name="CurrentStep" access="read"/>
-    <property type="b" name="Finished" access="read"/>
-    <property type="as" name="Steps" access="read"/>
-  </interface>
-  <interface name="org.opensuse.Agama1.ServiceStatus">
-    <property type="aa{sv}" name="All" access="read"/>
-    <property type="u" name="Current" access="read"/>
-  </interface>
   <interface name="org.opensuse.Agama.Storage1">
     <method name="Probe">
     </method>
@@ -105,9 +81,6 @@
       <arg name="serialized_config" direction="out" type="s"/>
     </method>
   </interface>
-  <interface name="org.opensuse.Agama.Storage1.Devices">
-    <property type="aa{sv}" name="Actions" access="read"/>
-  </interface>
   <interface name="org.opensuse.Agama.Storage1.DASD.Manager">
     <method name="Probe">
     </method>
@@ -130,6 +103,9 @@
       <arg name="job" direction="out" type="o"/>
     </method>
   </interface>
+  <interface name="org.opensuse.Agama.Storage1.Devices">
+    <property type="aa{sv}" name="Actions" access="read"/>
+  </interface>
   <interface name="org.opensuse.Agama.Storage1.ISCSI.Initiator">
     <method name="Discover">
       <arg name="address" direction="in" type="s"/>
@@ -144,7 +120,7 @@
     <property type="s" name="InitiatorName" access="readwrite"/>
     <property type="b" name="IBFT" access="read"/>
   </interface>
-    <interface name="org.opensuse.Agama.Storage1.Proposal.Calculator">
+  <interface name="org.opensuse.Agama.Storage1.Proposal.Calculator">
     <method name="DefaultVolume">
       <arg name="mount_path" direction="in" type="s"/>
       <arg name="volume" direction="out" type="a{sv}"/>
@@ -157,18 +133,24 @@
     <property type="as" name="ProductMountPoints" access="read"/>
     <property type="as" name="EncryptionMethods" access="read"/>
   </interface>
-    <interface name="org.opensuse.Agama.Storage1.ZFCP.Manager">
+  <interface name="org.opensuse.Agama.Storage1.ZFCP.Manager">
     <method name="Probe">
     </method>
     <property type="b" name="AllowLUNScan" access="read"/>
   </interface>
   <interface name="org.opensuse.Agama1.Issues">
-    <property type="a(ssuu)" name="All" access="read"/>
+    <property type="a(sssuu)" name="All" access="read"/>
+  </interface>
+  <interface name="org.opensuse.Agama1.LocaleMixin">
+    <method name="SetLocale">
+      <arg name="locale" direction="in" type="s"/>
+    </method>
   </interface>
   <interface name="org.opensuse.Agama1.Progress">
     <property type="u" name="TotalSteps" access="read"/>
     <property type="(us)" name="CurrentStep" access="read"/>
     <property type="b" name="Finished" access="read"/>
+    <property type="as" name="Steps" access="read"/>
   </interface>
   <interface name="org.opensuse.Agama1.ServiceStatus">
     <property type="aa{sv}" name="All" access="read"/>
diff --git a/doc/dbus/bus/org.opensuse.Agama.Users1.bus.xml b/doc/dbus/bus/org.opensuse.Agama.Users1.bus.xml
index fcb0439338..6e13b3a3c7 100644
--- a/doc/dbus/bus/org.opensuse.Agama.Users1.bus.xml
+++ b/doc/dbus/bus/org.opensuse.Agama.Users1.bus.xml
@@ -1,6 +1,10 @@
-<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
-"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+<?xml version="1.0" encoding="UTF-8"?>
 <node name="/org/opensuse/Agama/Users1">
+  <interface name="org.freedesktop.DBus.Introspectable">
+    <method name="Introspect">
+      <arg name="xml_data" direction="out" type="s"/>
+    </method>
+  </interface>
   <interface name="org.freedesktop.DBus.Properties">
     <method name="Get">
       <arg name="interface_name" direction="in" type="s"/>
@@ -22,18 +26,6 @@
       <arg name="invalidated_properties" type="as"/>
     </signal>
   </interface>
-  <interface name="org.freedesktop.DBus.Introspectable">
-    <method name="Introspect">
-      <arg name="xml_data" direction="out" type="s"/>
-    </method>
-  </interface>
-  <interface name="org.opensuse.Agama1.Issues">
-    <property type="a(sssuu)" name="All" access="read"/>
-  </interface>
-  <interface name="org.opensuse.Agama1.ServiceStatus">
-    <property type="aa{sv}" name="All" access="read"/>
-    <property type="u" name="Current" access="read"/>
-  </interface>
   <interface name="org.opensuse.Agama.Users1">
     <method name="SetRootPassword">
       <arg name="Value" direction="in" type="s"/>
@@ -64,4 +56,11 @@
     <property type="(sbs)" name="RootUser" access="read"/>
     <property type="(sssba{sv})" name="FirstUser" access="read"/>
   </interface>
+  <interface name="org.opensuse.Agama1.Issues">
+    <property type="a(sssuu)" name="All" access="read"/>
+  </interface>
+  <interface name="org.opensuse.Agama1.ServiceStatus">
+    <property type="aa{sv}" name="All" access="read"/>
+    <property type="u" name="Current" access="read"/>
+  </interface>
 </node>
diff --git a/doc/dbus/bus/org.opensuse.Agama1.Locale.bus.xml b/doc/dbus/bus/org.opensuse.Agama1.Locale.bus.xml
index 5170b7aaa0..7c2523d947 100644
--- a/doc/dbus/bus/org.opensuse.Agama1.Locale.bus.xml
+++ b/doc/dbus/bus/org.opensuse.Agama1.Locale.bus.xml
@@ -1,34 +1,58 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node>
   <interface name="org.freedesktop.DBus.Introspectable">
+    <!--
+     Returns an XML description of the object, including its interfaces (with signals and
+     methods), objects below it in the object path tree, and its properties.
+     -->
     <method name="Introspect">
       <arg type="s" direction="out"/>
     </method>
   </interface>
   <interface name="org.freedesktop.DBus.Peer">
+    <!--
+     On receipt, an application should do nothing other than reply as usual. It does not matter
+     which object path a ping is sent to.
+     -->
     <method name="Ping">
     </method>
+    <!--
+     An application should reply the containing a hex-encoded UUID representing the identity of
+     the machine the process is running on. This UUID must be the same for all processes on a
+     single system at least until that system next reboots. It should be the same across reboots
+     if possible, but this is not always possible to implement and is not guaranteed. It does not
+     matter which object path a GetMachineId is sent to.
+     -->
     <method name="GetMachineId">
       <arg type="s" direction="out"/>
     </method>
   </interface>
   <interface name="org.freedesktop.DBus.Properties">
+    <!--
+     Get a property value.
+     -->
     <method name="Get">
       <arg name="interface_name" type="s" direction="in"/>
       <arg name="property_name" type="s" direction="in"/>
       <arg type="v" direction="out"/>
     </method>
+    <!--
+     Set a property value.
+     -->
     <method name="Set">
       <arg name="interface_name" type="s" direction="in"/>
       <arg name="property_name" type="s" direction="in"/>
       <arg name="value" type="v" direction="in"/>
     </method>
+    <!--
+     Get all properties.
+     -->
     <method name="GetAll">
       <arg name="interface_name" type="s" direction="in"/>
       <arg type="a{sv}" direction="out"/>
     </method>
     <!--
-     Emits the `org.freedesktop.DBus.Properties.PropertiesChanged` signal.
+     Emit the `org.freedesktop.DBus.Properties.PropertiesChanged` signal.
      -->
     <signal name="PropertiesChanged">
       <arg name="interface_name" type="s"/>
@@ -37,46 +61,6 @@
     </signal>
   </interface>
   <interface name="org.opensuse.Agama1.Locale">
-    <!--
-     Gets the supported locales information.
-
-     Each element of the list has these parts:
-
-     * The locale code (e.g., "es_ES.UTF-8").
-     * The name of the language according to the language defined by the
-       UILocale property.
-     * The name of the territory according to the language defined by the
-       UILocale property.
-     -->
-    <method name="ListLocales">
-      <arg type="a(sss)" direction="out"/>
-    </method>
-    <!--
-     Returns a list of the supported keymaps.
-
-     Each element of the list contains:
-
-     * The keymap identifier (e.g., "es" or "es(ast)").
-     * The name of the keyboard in language set by the UILocale property.
-     -->
-    <method name="ListKeymaps">
-      <arg type="a(ss)" direction="out"/>
-    </method>
-    <!--
-     Returns a list of the supported timezones.
-
-     Each element of the list contains:
-
-     * The timezone identifier (e.g., "Europe/Berlin").
-     * A list containing each part of the name in the language set by the
-       UILocale property.
-     * The name, in the language set by UILocale, of the main country
-       associated to the timezone (typically, the name of the city that is
-       part of the identifier) or empty string if there is no country.
-     -->
-    <method name="ListTimezones">
-      <arg type="a(sass)" direction="out"/>
-    </method>
     <method name="Commit">
     </method>
     <property name="Keymap" type="s" access="readwrite"/>
diff --git a/doc/dbus/bus/org.opensuse.Agama1.LocaleMixin.bus.xml b/doc/dbus/bus/org.opensuse.Agama1.LocaleMixin.bus.xml
new file mode 120000
index 0000000000..4db8ffd295
--- /dev/null
+++ b/doc/dbus/bus/org.opensuse.Agama1.LocaleMixin.bus.xml
@@ -0,0 +1 @@
+org.opensuse.Agama.Manager1.bus.xml
\ No newline at end of file
diff --git a/doc/dbus/bus/org.opensuse.Agama1.Manager.bus.xml b/doc/dbus/bus/org.opensuse.Agama1.Manager.bus.xml
deleted file mode 100644
index 060c3de4d2..0000000000
--- a/doc/dbus/bus/org.opensuse.Agama1.Manager.bus.xml
+++ /dev/null
@@ -1,59 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<node name="/org/opensuse/Agama1/Manager">
-  <interface name="org.freedesktop.DBus.Introspectable">
-    <method name="Introspect">
-      <arg name="xml_data" direction="out" type="s"/>
-    </method>
-  </interface>
-  <interface name="org.freedesktop.DBus.Properties">
-    <method name="Get">
-      <arg name="interface_name" direction="in" type="s"/>
-      <arg name="property_name" direction="in" type="s"/>
-      <arg name="value" direction="out" type="v"/>
-    </method>
-    <method name="Set">
-      <arg name="interface_name" direction="in" type="s"/>
-      <arg name="property_name" direction="in" type="s"/>
-      <arg name="val" direction="in" type="v"/>
-    </method>
-    <method name="GetAll">
-      <arg name="interface_name" direction="in" type="s"/>
-      <arg name="value" direction="out" type="a{sv}"/>
-    </method>
-    <signal name="PropertiesChanged">
-      <arg name="interface" type="s"/>
-      <arg name="changed_properties" type="a{sv}"/>
-      <arg name="invalidated_properties" type="as"/>
-    </signal>
-  </interface>
-  <interface name="org.opensuse.Agama1.Manager">
-    <method name="Probe">
-    </method>
-    <method name="Commit">
-    </method>
-    <method name="CanInstall">
-      <arg name="result" direction="out" type="b"/>
-    </method>
-    <method name="CollectLogs">
-      <arg name="user" direction="in" type="s"/>
-      <arg name="tarball_filesystem_path" direction="out" type="s"/>
-    </method>
-    <method name="Finish">
-      <arg name="method" direction="in" type="s"/>
-      <arg name="result" direction="out" type="b"/>
-    </method>
-    <property type="aa{sv}" name="InstallationPhases" access="read"/>
-    <property type="u" name="CurrentInstallationPhase" access="read"/>
-    <property type="b" name="IguanaBackend" access="read"/>
-    <property type="as" name="BusyServices" access="read"/>
-  </interface>
-  <interface name="org.opensuse.Agama1.Progress">
-    <property type="u" name="TotalSteps" access="read"/>
-    <property type="(us)" name="CurrentStep" access="read"/>
-    <property type="b" name="Finished" access="read"/>
-  </interface>
-  <interface name="org.opensuse.Agama1.ServiceStatus">
-    <property type="aa{sv}" name="All" access="read"/>
-    <property type="u" name="Current" access="read"/>
-  </interface>
-</node>
diff --git a/doc/dbus/bus/org.opensuse.Agama1.Questions.Generic.bus.xml b/doc/dbus/bus/org.opensuse.Agama1.Questions.Generic.bus.xml
index 0bc9fe9d10..2145b26d8b 100644
--- a/doc/dbus/bus/org.opensuse.Agama1.Questions.Generic.bus.xml
+++ b/doc/dbus/bus/org.opensuse.Agama1.Questions.Generic.bus.xml
@@ -1,34 +1,58 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node>
   <interface name="org.freedesktop.DBus.Introspectable">
+    <!--
+     Returns an XML description of the object, including its interfaces (with signals and
+     methods), objects below it in the object path tree, and its properties.
+     -->
     <method name="Introspect">
       <arg type="s" direction="out"/>
     </method>
   </interface>
   <interface name="org.freedesktop.DBus.Peer">
+    <!--
+     On receipt, an application should do nothing other than reply as usual. It does not matter
+     which object path a ping is sent to.
+     -->
     <method name="Ping">
     </method>
+    <!--
+     An application should reply the containing a hex-encoded UUID representing the identity of
+     the machine the process is running on. This UUID must be the same for all processes on a
+     single system at least until that system next reboots. It should be the same across reboots
+     if possible, but this is not always possible to implement and is not guaranteed. It does not
+     matter which object path a GetMachineId is sent to.
+     -->
     <method name="GetMachineId">
       <arg type="s" direction="out"/>
     </method>
   </interface>
   <interface name="org.freedesktop.DBus.Properties">
+    <!--
+     Get a property value.
+     -->
     <method name="Get">
       <arg name="interface_name" type="s" direction="in"/>
       <arg name="property_name" type="s" direction="in"/>
       <arg type="v" direction="out"/>
     </method>
+    <!--
+     Set a property value.
+     -->
     <method name="Set">
       <arg name="interface_name" type="s" direction="in"/>
       <arg name="property_name" type="s" direction="in"/>
       <arg name="value" type="v" direction="in"/>
     </method>
+    <!--
+     Get all properties.
+     -->
     <method name="GetAll">
       <arg name="interface_name" type="s" direction="in"/>
       <arg type="a{sv}" direction="out"/>
     </method>
     <!--
-     Emits the `org.freedesktop.DBus.Properties.PropertiesChanged` signal.
+     Emit the `org.freedesktop.DBus.Properties.PropertiesChanged` signal.
      -->
     <signal name="PropertiesChanged">
       <arg name="interface_name" type="s"/>
diff --git a/doc/dbus/bus/org.opensuse.Agama1.Questions.WithPassword.bus.xml b/doc/dbus/bus/org.opensuse.Agama1.Questions.WithPassword.bus.xml
index f9dd49994c..7e85448d49 100644
--- a/doc/dbus/bus/org.opensuse.Agama1.Questions.WithPassword.bus.xml
+++ b/doc/dbus/bus/org.opensuse.Agama1.Questions.WithPassword.bus.xml
@@ -1,34 +1,58 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node>
   <interface name="org.freedesktop.DBus.Introspectable">
+    <!--
+     Returns an XML description of the object, including its interfaces (with signals and
+     methods), objects below it in the object path tree, and its properties.
+     -->
     <method name="Introspect">
       <arg type="s" direction="out"/>
     </method>
   </interface>
   <interface name="org.freedesktop.DBus.Peer">
+    <!--
+     On receipt, an application should do nothing other than reply as usual. It does not matter
+     which object path a ping is sent to.
+     -->
     <method name="Ping">
     </method>
+    <!--
+     An application should reply the containing a hex-encoded UUID representing the identity of
+     the machine the process is running on. This UUID must be the same for all processes on a
+     single system at least until that system next reboots. It should be the same across reboots
+     if possible, but this is not always possible to implement and is not guaranteed. It does not
+     matter which object path a GetMachineId is sent to.
+     -->
     <method name="GetMachineId">
       <arg type="s" direction="out"/>
     </method>
   </interface>
   <interface name="org.freedesktop.DBus.Properties">
+    <!--
+     Get a property value.
+     -->
     <method name="Get">
       <arg name="interface_name" type="s" direction="in"/>
       <arg name="property_name" type="s" direction="in"/>
       <arg type="v" direction="out"/>
     </method>
+    <!--
+     Set a property value.
+     -->
     <method name="Set">
       <arg name="interface_name" type="s" direction="in"/>
       <arg name="property_name" type="s" direction="in"/>
       <arg name="value" type="v" direction="in"/>
     </method>
+    <!--
+     Get all properties.
+     -->
     <method name="GetAll">
       <arg name="interface_name" type="s" direction="in"/>
       <arg type="a{sv}" direction="out"/>
     </method>
     <!--
-     Emits the `org.freedesktop.DBus.Properties.PropertiesChanged` signal.
+     Emit the `org.freedesktop.DBus.Properties.PropertiesChanged` signal.
      -->
     <signal name="PropertiesChanged">
       <arg name="interface_name" type="s"/>
diff --git a/doc/dbus/bus/org.opensuse.Agama1.Questions.bus.xml b/doc/dbus/bus/org.opensuse.Agama1.Questions.bus.xml
index 6a85392d5c..5e7a93cccc 100644
--- a/doc/dbus/bus/org.opensuse.Agama1.Questions.bus.xml
+++ b/doc/dbus/bus/org.opensuse.Agama1.Questions.bus.xml
@@ -1,11 +1,25 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node>
   <interface name="org.freedesktop.DBus.Introspectable">
+    <!--
+     Returns an XML description of the object, including its interfaces (with signals and
+     methods), objects below it in the object path tree, and its properties.
+     -->
     <method name="Introspect">
       <arg type="s" direction="out"/>
     </method>
   </interface>
   <interface name="org.freedesktop.DBus.ObjectManager">
+    <!--
+     The return value of this method is a dict whose keys are object paths. All returned object
+     paths are children of the object path implementing this interface, i.e. their object paths
+     start with the ObjectManager's object path plus '/'.
+
+     Each value is a dict whose keys are interfaces names. Each value in this inner dict is the
+     same dict that would be returned by the org.freedesktop.DBus.Properties.GetAll() method for
+     that combination of object path and interface. If an interface has no properties, the empty
+     dict is returned.
+     -->
     <method name="GetManagedObjects">
       <arg type="a{oa{sa{sv}}}" direction="out"/>
     </method>
@@ -28,29 +42,49 @@
     </signal>
   </interface>
   <interface name="org.freedesktop.DBus.Peer">
+    <!--
+     On receipt, an application should do nothing other than reply as usual. It does not matter
+     which object path a ping is sent to.
+     -->
     <method name="Ping">
     </method>
+    <!--
+     An application should reply the containing a hex-encoded UUID representing the identity of
+     the machine the process is running on. This UUID must be the same for all processes on a
+     single system at least until that system next reboots. It should be the same across reboots
+     if possible, but this is not always possible to implement and is not guaranteed. It does not
+     matter which object path a GetMachineId is sent to.
+     -->
     <method name="GetMachineId">
       <arg type="s" direction="out"/>
     </method>
   </interface>
   <interface name="org.freedesktop.DBus.Properties">
+    <!--
+     Get a property value.
+     -->
     <method name="Get">
       <arg name="interface_name" type="s" direction="in"/>
       <arg name="property_name" type="s" direction="in"/>
       <arg type="v" direction="out"/>
     </method>
+    <!--
+     Set a property value.
+     -->
     <method name="Set">
       <arg name="interface_name" type="s" direction="in"/>
       <arg name="property_name" type="s" direction="in"/>
       <arg name="value" type="v" direction="in"/>
     </method>
+    <!--
+     Get all properties.
+     -->
     <method name="GetAll">
       <arg name="interface_name" type="s" direction="in"/>
       <arg type="a{sv}" direction="out"/>
     </method>
     <!--
-     Emits the `org.freedesktop.DBus.Properties.PropertiesChanged` signal.
+     Emit the `org.freedesktop.DBus.Properties.PropertiesChanged` signal.
      -->
     <signal name="PropertiesChanged">
       <arg name="interface_name" type="s"/>
@@ -83,6 +117,7 @@
     </method>
     <!--
      Removes question at given object path
+     TODO: use id as parameter ( need at first check other users of method )
      -->
     <method name="Delete">
       <arg name="question" type="o" direction="in"/>
diff --git a/doc/dbus/compare-impl-and-docs b/doc/dbus/compare-impl-and-docs
new file mode 100755
index 0000000000..e6c2fbb996
--- /dev/null
+++ b/doc/dbus/compare-impl-and-docs
@@ -0,0 +1,40 @@
+#!/bin/sh
+# check that the implementation and documentation haven't diverged
+set -eu
+
+# TODO help message
+tmpdir=$1
+mkdir -p "$tmpdir"
+
+NO_COMMENTS="xmlstarlet --quiet canonic --without-comments"
+ALL_GOOD=true
+for doc_xml in org.opensuse.Agama*.doc.xml; do
+	IFACE="${doc_xml%.doc.xml}"
+	bus_xml=bus/$IFACE.bus.xml
+	doc_iface="$tmpdir"/$IFACE.doc.iface.xml
+	bus_iface="$tmpdir"/$IFACE.bus.iface.xml
+	
+	echo "Diffing $IFACE"
+	
+	${NO_COMMENTS} \
+	  "$doc_xml" \
+	  > "$doc_iface"
+
+	xmlstarlet ed \
+      -d "//interface[@name!='$IFACE']" \
+      "$bus_xml" \
+      | ${NO_COMMENTS} - \
+	  > "$bus_iface"
+
+	# using ALL_GOOD means show diffs for all interfaces, not only the first one
+	diff --ignore-blank-lines --ignore-trailing-space -u "$doc_iface" "$bus_iface" || ALL_GOOD=false
+done
+
+if $ALL_GOOD; then
+	echo "NO DIFF, YAY"
+else
+	echo "error: In the above diff, ignore the whitespace changes."
+	echo "error: Observe the API changes and make sure they are documented in *.doc.xml"
+	# fail the check
+	false
+fi
diff --git a/doc/dbus/make-index b/doc/dbus/make-index
index 4c97fe442e..42d7aed5e3 100755
--- a/doc/dbus/make-index
+++ b/doc/dbus/make-index
@@ -1,6 +1,12 @@
 #!/bin/sh
-echo "<!-- do not edit: generated by make-index -->"
-echo "<head><title>Agama D-Bus API</title></head>"
+cat <<EOS
+<!-- do not edit: generated by make-index -->
+<head>
+<title>Agama D-Bus API</title>
+<link rel="stylesheet" href="refentry-agama.css" type="text/css">
+</head>
+EOS
+
 echo "<ul>"
 for F in tmp/ref-*.xml; do
   F=${F#tmp/}
@@ -9,4 +15,4 @@ for F in tmp/ref-*.xml; do
   echo "                >${F#ref-}</a></li>"
 done
 echo "</ul>"
-echo "<a href="..">up</a>"
+echo "<a href=\"..\">up</a>"
diff --git a/doc/dbus/org.opensuse.Agama1.Manager.doc.xml b/doc/dbus/org.opensuse.Agama.Manager1.doc.xml
similarity index 93%
rename from doc/dbus/org.opensuse.Agama1.Manager.doc.xml
rename to doc/dbus/org.opensuse.Agama.Manager1.doc.xml
index 13dd26b9a5..bf427e393a 100644
--- a/doc/dbus/org.opensuse.Agama1.Manager.doc.xml
+++ b/doc/dbus/org.opensuse.Agama.Manager1.doc.xml
@@ -1,7 +1,7 @@
 <!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
 "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
-<node name="/org/opensuse/Agama1/Manager">
-  <interface name="org.opensuse.Agama1.Manager">
+<node name="/org/opensuse/Agama/Manager1">
+  <interface name="org.opensuse.Agama.Manager1">
     <method name="Probe">
     </method>
     <method name="Commit">
@@ -10,12 +10,10 @@
       <arg name="result" direction="out" type="b"/>
     </method>
     <method name="CollectLogs">
-      <arg name="user" direction="in" type="s"/>
       <arg name="tarball_filesystem_path" direction="out" type="s"/>
     </method>
-    <method name="Finish">
-      <!--
-       Finish method.
+    <!--
+       Finish:
 
        Possible values are: "stop", "reboot", "poweroff", "halt"
 
@@ -32,15 +30,16 @@
        * *halt*:
        Finish the installation calling shutdown -H
 
-       -->
+    -->
+    <method name="Finish">
       <arg name="method" direction="in" type="s"/>
       <arg name="result" direction="out" type="b"/>
     </method>
 
     <!--
-        InstallationPhases:
+InstallationPhases:
 
-  All possible phases:
+All possible phases:
 <programlisting>
 [
     {"id" => 0, "label" => "startup"},
diff --git a/doc/dbus/org.opensuse.Agama.Software1.Product.doc.xml b/doc/dbus/org.opensuse.Agama.Software1.Product.doc.xml
index 165a67094b..9f174437dd 100644
--- a/doc/dbus/org.opensuse.Agama.Software1.Product.doc.xml
+++ b/doc/dbus/org.opensuse.Agama.Software1.Product.doc.xml
@@ -2,25 +2,24 @@
 <node name="/org/opensuse/Agama/Software1/Product">
   <interface name="org.opensuse.Agama.Software1.Product">
     <!--
+      SelectProduct:
+      @id: Product ID. See #AvailableProducts.
+      @result: Result code and description.
+
       Selects a product.
-    -->
-    <method name="SelectProduct">
-      <!--
-        Product ID. See #AvailableProducts.
-      -->
-      <arg name="id" direction="in" type="s"/>
-      <!--
-        Result code and description.
 
-        Possible result codes are:
+      Possible result codes are:
         #   0: successfully selected
         #   1: given product is already selected
         #   2: current product must be deregistered before selecting a new product
         #   3: given product is unknown
-      -->
+    -->
+    <method name="SelectProduct">
+      <arg name="id" direction="in" type="s"/>
       <arg name="result" direction="out" type="(us)"/>
     </method>
     <!--
+      AvailableProducts:
       Available products for installation.
 
       For each product, it returns:
@@ -31,6 +30,7 @@
     -->
     <property type="a(ssa{sv})" name="AvailableProducts" access="read"/>
     <!--
+      SelectedProduct:
       ID of the currently selected product.
     -->
     <property type="s" name="SelectedProduct" access="read"/>
diff --git a/doc/dbus/org.opensuse.Agama.Software1.doc.xml b/doc/dbus/org.opensuse.Agama.Software1.doc.xml
index 0080f876ff..fd558b2317 100644
--- a/doc/dbus/org.opensuse.Agama.Software1.doc.xml
+++ b/doc/dbus/org.opensuse.Agama.Software1.doc.xml
@@ -4,67 +4,68 @@
   <node name="Proposal"/>
 
   <interface name="org.opensuse.Agama.Software1">
+    <method name="ListRepositories">
+      <arg direction="out" name="Result" type="a(issssbb)"></arg>
+    </method>
+
     <!--
+      ListPatterns:
+      @Filtered: Flag if all or filtered only patterns.
+      @Result: Result of search for patterns.
+
       List available patterns.
-    -->
-    <method name="ListPatterns">
-      <!--
-        Flag if all or filtered only patterns. Way how it is filtered
+
+        Way how it is filtered
         is internal details and basically it can change anytime.
         Filtered patterns are the one to show users for selection.
         For validation if patterns are valid, unfiltered should be used.
-      -->
-      <arg name="Filtered" direction="in" type="b"/>
-      <!--
-        Result of search for patterns. It is Map with pattern id as key and those values
+
+        @Result is Map with pattern id as key and those values
         1. category of pattern. Useful for grouping patterns if needed
         2. description of pattern
         3. path to icon on local system
         4. summary of pattern
         5. order value for sorting patterns
       -->
+    <method name="ListPatterns">
+      <arg name="Filtered" direction="in" type="b"/>
       <arg name="Result" direction="out" type="a{s(sssss)}"/>
     </method>
     <!--
+      AddPattern:
+      @id: Identifier of pattern.
+      @result: Returns false if pattern does not exist in current list of repositories. Otherwise it returns true.
+
       Adds pattern to explicitelly selected ones.
     -->
     <method name="AddPattern">
-      <!--
-        Identifier of pattern.
-      -->
       <arg name="id" direction="in" type="s"/>
-      <!--
-        Returns false if pattern does not exist in current list of repositories.
-        Otherwise it returns true.
-      -->
       <arg name="result" direction="out" type="b"/>
     </method>
     <!--
+      RemovePattern:
+      @id: Identifier of pattern.
+      @result: Returns false if pattern does not exist in current list of repositories. Otherwise it returns true including case when pattern was not previously selected.
+
       Removes pattern from explicit selection. It can still be installed as dependency.
     -->
     <method name="RemovePattern">
-      <!--
-        Identifier of pattern.
-      -->
       <arg name="id" direction="in" type="s"/>
-      <!--
-        Returns false if pattern does not exist in current list of repositories.
-        Otherwise it returns true including case when pattern was not previously selected.
-      -->
       <arg name="result" direction="out" type="b"/>
     </method>
     <!--
-      Sets explicitly selected patterns.
+        SetUserPatterns:
+        @add:    patterns to add
+        @remove: patterns to remove
+        @wrong:  Return list of non existing patterns.
+
+        Sets explicitly selected patterns.
+
+        Operation was basically cancelled if result is not empty.
     -->
     <method name="SetUserPatterns">
-      <!--
-        List of pattern ids.
-      -->
-      <arg name="ids" direction="in" type="as"/>
-      <!--
-        Return list of non existing patterns.
-        Operation was basically cancelled if result is not empty.
-      -->
+      <arg name="add" direction="in" type="as"/>
+      <arg name="remove" direction="in" type="as"/>
       <arg name="wrong" direction="out" type="as"/>
     </method>
     <method name="ProvisionsSelected">
@@ -76,12 +77,11 @@
       <arg name="Result" direction="out" type="b"/>
     </method>
     <!--
+      IsPackageAvailable:
+      @name: Name of the package.
       Whether a package is available for installation.
     -->
     <method name="IsPackageAvailable">
-      <!--
-        Name of the package.
-      -->
       <arg name="name" direction="in" type="s"/>
       <arg name="result" direction="out" type="b"/>
     </method>
@@ -96,6 +96,8 @@
     </method>
     <method name="Finish">
     </method>
+    <signal name="ProbeFinished">
+    </signal>
     <property type="a{sy}" name="SelectedPatterns" access="read"/>
   </interface>
 </node>
diff --git a/doc/dbus/org.opensuse.Agama.Storage1.ISCSI.Initiator.doc.xml b/doc/dbus/org.opensuse.Agama.Storage1.ISCSI.Initiator.doc.xml
index 8773ecb5e3..43aab40345 100644
--- a/doc/dbus/org.opensuse.Agama.Storage1.ISCSI.Initiator.doc.xml
+++ b/doc/dbus/org.opensuse.Agama.Storage1.ISCSI.Initiator.doc.xml
@@ -2,11 +2,6 @@
 "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
 <node name="/org/opensuse/Agama/Storage1">
   <node name="ISCSI" />
-  <node name="iscsi_nodes" />
-  <node name="staging" />
-  <node name="system" />
-  <node name="zfcp_controllers" />
-  <node name="zfcp_disks" />
   <interface name="org.opensuse.Agama.Storage1.ISCSI.Initiator">
     <method name="Discover">
       <arg name="address" direction="in" type="s"/>
diff --git a/doc/dbus/org.opensuse.Agama.Storage1.ISCSI.doc.xml b/doc/dbus/org.opensuse.Agama.Storage1.ISCSI.doc.xml
index ce66e330e6..a6347c9c60 100644
--- a/doc/dbus/org.opensuse.Agama.Storage1.ISCSI.doc.xml
+++ b/doc/dbus/org.opensuse.Agama.Storage1.ISCSI.doc.xml
@@ -4,17 +4,11 @@
   <interface name="org.opensuse.Agama.Storage1.ISCSI">
     <!--
       Sets the iSCSI config.
+      @serialized_config: See iscsi.schema.json
+      @result: Whether the config was correctly applied: 0: success, 1: failure
     -->
     <method name="SetConfig">
-      <!--
-        See iscsi.schema.json
-      -->
       <arg name="serialized_config" direction="in" type="s"/>
-      <!--
-        Whether the config was correctly applied:
-          0: success
-          1: failure
-      -->
       <arg name="result" direction="out" type="u"/>
     </method>
   </interface>
diff --git a/doc/dbus/org.opensuse.Agama.Storage1.Proposal.Calculator.doc.xml b/doc/dbus/org.opensuse.Agama.Storage1.Proposal.Calculator.doc.xml
index 14068f2812..211a0a2453 100644
--- a/doc/dbus/org.opensuse.Agama.Storage1.Proposal.Calculator.doc.xml
+++ b/doc/dbus/org.opensuse.Agama.Storage1.Proposal.Calculator.doc.xml
@@ -2,24 +2,19 @@
 "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
 <node name="/org/opensuse/Agama/Storage1">
   <node name="ISCSI" />
-  <node name="iscsi_nodes" />
-  <node name="staging" />
-  <node name="system" />
-  <node name="zfcp_controllers" />
-  <node name="zfcp_disks" />
   <!--
-    Interface for calculating a new storage proposal.
+    org.opensuse.Agama.Storage1.Proposal.Calculator
+    @short_description: Interface for calculating a new storage proposal.
   -->
   <interface name="org.opensuse.Agama.Storage1.Proposal.Calculator">
     <!--
+      DefaultVolume:
+      @mount_path: E.g., /home
+
       Gets the default values for a volume with the given mount path.
-    -->
-    <method name="DefaultVolume">
-      <!--
-        E.g., /home
-      -->
-      <arg name="mount_path" direction="in" type="s"/>
-      <!--
+
+      Returns:
+      <programlisting>
         MountPath               s
         MountOptions            as
         Target                  s (options: "default", "new_partition", "new_vg", "device", "filesystem")
@@ -37,14 +32,20 @@
           SnapshotsConfigurable b
           SnapshotsAffectSizes  b
           SizeRelevantVolumes   as
-      -->
+      </programlisting>
+    -->
+    <method name="DefaultVolume">
+      <arg name="mount_path" direction="in" type="s"/>
       <arg name="volume" direction="out" type="a{sv}"/>
     </method>
     <!--
+      Calculate:
+      @result: Whether the proposal was correctly calculated: 0: success, 1: failure
+
       Calculates a new proposal.
-    -->
-    <method name="Calculate">
-      <!--
+
+      Input:
+      <programlisting>
         Target                 s (options: "disk", "newLvmVg", "reusedLvmVg")
         TargeDevice            s (optional: does not make sense if Target is "newLvmVg")
         TargetPVDevices        as (optional: only makes sense if Target is "newLvmVg")
@@ -56,12 +57,16 @@
         SpacePolicy            s
         SpaceActions           aa{sv}
         Volumes                aa{sv}
+      </programlisting>
 
-        Each space action has the following properties:
+      Each space action has the following properties:
+      <programlisting>
           Device                 s
           Action                 s (options: "force_delete", "resize")
+      </programlisting>
 
-        Each volume has the following properties:
+      Each volume has the following properties:
+      <programlisting>
           MountPath               s
           MountOptions            as
           Target                  s (options: "default", "new_partition", "new_vg", "device", "filesystem")
@@ -72,22 +77,19 @@
           AutoSize                b
           Snapshots               b (makes sense only for btrfs)
           Transactional           b (makes sense only for btrfs)
-      -->
+      </programlisting>
+    -->
+    <method name="Calculate">
       <arg name="settings_dbus" direction="in" type="a{sv}"/>
-      <!--
-        Whether the proposal was correctly calculated:
-          0: success
-          1: failure
-      -->
       <arg name="result" direction="out" type="u"/>
     </method>
     <property type="ao" name="AvailableDevices" access="read"/>
     <!--
+      ProductMountPoints:
       Relevant mount points for the selected product. Normally, the product defines some specific
       values for these mount points (e.g., min and max sizes, file system type, etc).
     -->
     <property type="as" name="ProductMountPoints" access="read"/>
     <property type="as" name="EncryptionMethods" access="read"/>
   </interface>
-
 </node>
diff --git a/doc/dbus/org.opensuse.Agama.Storage1.Proposal.doc.xml b/doc/dbus/org.opensuse.Agama.Storage1.Proposal.doc.xml
index 9b7bea10ab..43a693dfe6 100644
--- a/doc/dbus/org.opensuse.Agama.Storage1.Proposal.doc.xml
+++ b/doc/dbus/org.opensuse.Agama.Storage1.Proposal.doc.xml
@@ -1,11 +1,15 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/org/opensuse/Agama/Storage1/Proposal">
   <!--
-    Interfaces with the properties of the calculated proposal.
+    org.opensuse.Agama.Storage1.Proposal:
+    @short_description: Interfaces with the properties of the calculated proposal.
   -->
   <interface name="org.opensuse.Agama.Storage1.Proposal">
     <!--
+      Settings:
       Proposal settings:
+
+      <programlisting>
         Target                 s (options: "disk", "newLvmVg", "reusedLvmVg")
         TargeDevice            s (optional: does not make sense if Target is "newLvmVg")
         TargetPVDevices        as (optional: only makes sense if Target is "newLvmVg")
@@ -18,12 +22,16 @@
         SpacePolicy            s
         SpaceActions           aa{sv}
         Volumes                aa{sv}
+      </programlisting>
 
       Each space action has the following properties:
+      <programlisting>
         Device                 s
         Action                 s (options: "force_delete", "resize")
+      </programlisting>
 
       Each volume has the following properties:
+      <programlisting>
         MountPath               s
         MountOptions            as
         Target                  s (options: "default", "new_partition", "new_vg", "device", "filesystem")
@@ -41,15 +49,19 @@
           SnapshotsConfigurable b
           SnapshotsAffectSizes  b
           SizeRelevantVolumes   as
+      </programlisting>
     -->
     <property type="a{sv}" name="Settings" access="read"/>
     <!--
+      Actions:
       Actions to perform in the system in order to create the volumes.
       Each action has the following properties:
+      <programlisting>
         Device  s
         Text    s
         Subvol  b
         Delete  b
+      </programlisting>
     -->
     <property type="aa{sv}" name="Actions" access="read"/>
   </interface>
diff --git a/doc/dbus/org.opensuse.Agama.Storage1.ZFCP.Controller.doc.xml b/doc/dbus/org.opensuse.Agama.Storage1.ZFCP.Controller.doc.xml
index 04e45a262b..ee145c498d 100644
--- a/doc/dbus/org.opensuse.Agama.Storage1.ZFCP.Controller.doc.xml
+++ b/doc/dbus/org.opensuse.Agama.Storage1.ZFCP.Controller.doc.xml
@@ -2,88 +2,89 @@
 "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
 <node>
   <!--
-    Interface for managing a zFCP controller, see
-    https://www.ibm.com/docs/en/linux-on-systems?topic=cd-manually-configured-fcp-luns-1
+    org.opensuse.Agama.Storage1.ZFCP.Controller:
+    @short_description: Interface for managing a zFCP controller
+
+    see https://www.ibm.com/docs/en/linux-on-systems?topic=cd-manually-configured-fcp-luns-1
   -->
   <interface name="org.opensuse.Agama.Storage1.ZFCP.Controller">
     <!--
+      GetWWPNs:
+      @result: E.g., 0x500507630300c562 0x500507630300c563
       Gets the list of WWPNs (World Wide Port Name)
     -->
     <method name="GetWWPNs">
-      <!--
-        E.g., 0x500507630300c562 0x500507630300c563
-      -->
       <arg name="result" direction="out" type="as"/>
     </method>
+
     <!--
+      GetLUNs:
+      @result: E.g., 0x4010403300000000 0x4010403300000001 0x4010403300000002
+      @wwpn: E.g., 0x500507630300c562
+
       Gets the list of LUNs (Local Unit Number)
     -->
     <method name="GetLUNs">
-      <!--
-        E.g., 0x500507630300c562
-      -->
       <arg name="wwpn" direction="in" type="s"/>
-      <!--
-        E.g., 0x4010403300000000 0x4010403300000001 0x4010403300000002
-      -->
       <arg name="result" direction="out" type="as"/>
     </method>
+
     <!--
+      Activate:
+      @result: Exit code of the chzdev command.
+
       Activates the zFCP controller.
 
       If allow_lun_scan is active, then all LUNs are automatically activated.
     -->
     <method name="Activate">
-      <!--
-        Exit code of the chzdev command.
-      -->
       <arg name="result" direction="out" type="u"/>
     </method>
+
     <!--
+      ActivateDisk:
+      @wwpn: E.g., 0x500507630300c562
+      @lun: E.g., 0x4010403300000000
+      @result: Exit code of the chzdev command.
+
       Activates a zFCP disk.
     -->
     <method name="ActivateDisk">
-      <!--
-        E.g., 0x500507630300c562
-      -->
       <arg name="wwpn" direction="in" type="s"/>
-      <!--
-        E.g., 0x4010403300000000
-      -->
       <arg name="lun" direction="in" type="s"/>
-      <!--
-        Exit code of the chzdev command.
-      -->
       <arg name="result" direction="out" type="u"/>
     </method>
+
     <!--
+      DeactivateDisk:
+      @wwpn: E.g., 0x500507630300c562
+      @lun: E.g., 0x4010403300000000
+      @result: Exit code of the chzdev command.
+
       Deactivates a zFCP disk.
 
       If "allow_lun_scan" is active, then the disk cannot be deactivated.
     -->
     <method name="DeactivateDisk">
-      <!--
-        E.g., 0x500507630300c562
-      -->
       <arg name="wwpn" direction="in" type="s"/>
-      <!--
-        E.g., 0x4010403300000000
-      -->
       <arg name="lun" direction="in" type="s"/>
-      <!--
-        Exit code of the chzdev command.
-      -->
       <arg name="result" direction="out" type="u"/>
     </method>
+
     <!--
+      Active:
       Whether the controller is active.
     -->
     <property type="b" name="Active" access="read"/>
+
     <!--
+      LUNScan:
       Whether the controller is performing auto LUN scan.
     -->
     <property type="b" name="LUNScan" access="read"/>
+
     <!--
+      Channel:
       zFCP channel id (e.g., 0.0.fa00).
     -->
     <property type="s" name="Channel" access="read"/>
diff --git a/doc/dbus/org.opensuse.Agama.Storage1.ZFCP.Disk.doc.xml b/doc/dbus/org.opensuse.Agama.Storage1.ZFCP.Disk.doc.xml
index 3862cc309e..95c710aae1 100644
--- a/doc/dbus/org.opensuse.Agama.Storage1.ZFCP.Disk.doc.xml
+++ b/doc/dbus/org.opensuse.Agama.Storage1.ZFCP.Disk.doc.xml
@@ -2,22 +2,27 @@
 "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
 <node>
   <!--
-    Interface for a zFCP disk
+    org.opensuse.Agama.Storage1.ZFCP.Disk:
+    @short_description: Interface for a zFCP disk
   -->
   <interface name="org.opensuse.Agama.Storage1.ZFCP.Disk">
     <!--
+      Name:
       Name of the SCSI device (e.g., /dev/sda)
     -->
     <property type="s" name="Name" access="read"/>
     <!--
+      Channel:
       zFCP controller channel id (e.g., 0.0.fa00).
     -->
     <property type="s" name="Channel" access="read"/>
     <!--
+      WWPN:
       WWPN of the targer port (e.g., 0x500507630300c562)
     -->
     <property type="s" name="WWPN" access="read"/>
     <!--
+      LUN:
       LUN of the SCSI device (e.g. 0x4010403300000000)
     -->
     <property type="s" name="LUN" access="read"/>
diff --git a/doc/dbus/org.opensuse.Agama.Storage1.ZFCP.Manager.doc.xml b/doc/dbus/org.opensuse.Agama.Storage1.ZFCP.Manager.doc.xml
index b7e40f85ef..d56330773e 100644
--- a/doc/dbus/org.opensuse.Agama.Storage1.ZFCP.Manager.doc.xml
+++ b/doc/dbus/org.opensuse.Agama.Storage1.ZFCP.Manager.doc.xml
@@ -3,11 +3,13 @@
 <node name="/org/opensuse/Agama/Storage1">
   <interface name="org.opensuse.Agama.Storage1.ZFCP.Manager">
     <!--
+      Probe:
       Probes the zFCP controllers and disks.
     -->
     <method name="Probe">
     </method>
     <!--
+      AllowLUNScan:
       Whether the option allow_lun_scan is active.
     -->
     <property type="b" name="AllowLUNScan" access="read"/>
diff --git a/doc/dbus/org.opensuse.Agama.Storage1.doc.xml b/doc/dbus/org.opensuse.Agama.Storage1.doc.xml
index 8c1a49df11..898a145059 100644
--- a/doc/dbus/org.opensuse.Agama.Storage1.doc.xml
+++ b/doc/dbus/org.opensuse.Agama.Storage1.doc.xml
@@ -2,25 +2,23 @@
 "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
 <node name="/org/opensuse/Agama/Storage1">
   <node name="ISCSI" />
-  <node name="iscsi_nodes" />
-  <node name="staging" />
-  <node name="system" />
-  <node name="zfcp_controllers" />
-  <node name="zfcp_disks" />
   <interface name="org.opensuse.Agama.Storage1">
     <method name="Probe">
     </method>
     <!--
+      Reprobe:
       Probes the system and recalculates the proposal using the current config.
     -->
     <method name="Reprobe">
     </method>
     <!--
+      SetConfig:
+      @result, Whether the proposal was correctly calculated: 0: success, 1: failure
+
       Sets the storage config.
-    -->
-    <method name="SetConfig">
-      <!--
-        E.g.,
+
+        @serialized_config, E.g.,
+        <programlisting>
         {
           "storage": {
             "drives": [
@@ -33,32 +31,27 @@
             ]
           }
         }
-      -->
+        </programlisting>
+    -->
+    <method name="SetConfig">
       <arg name="serialized_config" direction="in" type="s"/>
-      <!--
-        Whether the proposal was correctly calculated:
-          0: success
-          1: failure
-      -->
       <arg name="result" direction="out" type="u"/>
     </method>
     <!--
+      ResetConfig:
+      @result: Whether the proposal was correctly calculated: 0: success, 1: failure
+
       Resets the default storage config defined by the selected product.
     -->
     <method name="ResetConfig">
-      <!--
-        Whether the proposal was correctly calculated:
-          0: success
-          1: failure
-      -->
       <arg name="result" direction="out" type="u"/>
     </method>
     <!--
+      GetConfig:
       Gets the unsolved storage config.
-    -->
-    <method name="GetConfig">
-      <!--
-        E.g.,
+
+        @serialized_config, e.g.
+        <programlisting>
         {
           "storage": {
             "drives": [
@@ -71,15 +64,19 @@
             ]
           }
         }
-      -->
+        </programlisting>
+    -->
+    <method name="GetConfig">
       <arg name="serialized_config" direction="out" type="s"/>
     </method>
     <!--
+      SetConfigModel:
+      @result: Whether the proposal was correctly calculated with the given config model: 0: success, 1: failure
+
       Sets the storage config model.
-    -->
-    <method name="SetConfigModel">
-      <!--
+
         E.g.,
+        <programlisting>
         {
           "drives": [
             {
@@ -90,21 +87,18 @@
             }
           ]
         }
-      -->
+        </programlisting>
+    -->
+    <method name="SetConfigModel">
       <arg name="serialized_model" direction="in" type="s"/>
-      <!--
-        Whether the proposal was correctly calculated with the given config model:
-          0: success
-          1: failure
-      -->
       <arg name="result" direction="out" type="u"/>
     </method>
     <!--
+      GetConfigModel:
       Gets the storage config model.
-    -->
-    <method name="GetConfigModel">
-      <!--
+
         E.g.,
+        <programlisting>
         {
           "drives": [
             {
@@ -127,14 +121,17 @@
             }
           ]
         }
-      -->
+        </programlisting>
+    -->
+    <method name="GetConfigModel">
       <arg name="serialized_model" direction="out" type="s"/>
     </method>
     <!--
+      SolveConfigModel:
       Solves the given storage config model.
-    -->
-    <method name="SolveConfigModel">
-      <!--
+
+      Input, e.g.
+      <programlisting>
         E.g.,
         {
           "drives": [
@@ -148,10 +145,10 @@
             }
           ]
         }
-      -->
-      <arg name="sparse_model" direction="in" type="s"/>
-      <!--
-        E.g.,
+        </programlisting>
+
+        Output, e.g.
+        <programlisting>
         {
           "drives": [
             {
@@ -174,14 +171,24 @@
             }
           ]
         }
-      -->
+        </programlisting>
+    -->
+    <method name="SolveConfigModel">
+      <arg name="sparse_model" direction="in" type="s"/>
       <arg name="solved_model" direction="out" type="s"/>
     </method>
+    <!--
+      Install:
+    -->
     <method name="Install">
     </method>
+    <!--
+      Finish:
+    -->
     <method name="Finish">
     </method>
     <!--
+      DeprecatedSystem:
       Whether the system is in a deprecated status.
 
       The system is usually set as deprecated as effect of managing some kind of devices, for
diff --git a/doc/dbus/org.opensuse.Agama1.Locale.doc.xml b/doc/dbus/org.opensuse.Agama1.Locale.doc.xml
index 8d1e32268b..12ce053f71 100644
--- a/doc/dbus/org.opensuse.Agama1.Locale.doc.xml
+++ b/doc/dbus/org.opensuse.Agama1.Locale.doc.xml
@@ -1,46 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node>
   <interface name="org.opensuse.Agama1.Locale">
-    <!--
-     Gets the supported locales information.
-
-     Each element of the list has these parts:
-
-     * The locale code (e.g., "es_ES.UTF-8").
-     * The name of the language according to the language defined by the
-       UILocale property.
-     * The name of the territory according to the language defined by the
-       UILocale property.
-     -->
-    <method name="ListLocales">
-      <arg type="a(sss)" direction="out"/>
-    </method>
-    <!--
-     Returns a list of the supported keymaps.
-
-     Each element of the list contains:
-
-     * The keymap identifier (e.g., "es" or "es(ast)").
-     * The name of the keyboard in language set by the UILocale property.
-     -->
-    <method name="ListKeymaps">
-      <arg type="a(ss)" direction="out"/>
-    </method>
-    <!--
-     Returns a list of the supported timezones.
-
-     Each element of the list contains:
-
-     * The timezone identifier (e.g., "Europe/Berlin").
-     * A list containing each part of the name in the language set by the
-       UILocale property.
-     * The name, in the language set by UILocale, of the main country
-       associated to the timezone (typically, the name of the city that is
-       part of the identifier) or empty string if there is no country.
-     -->
-    <method name="ListTimezones">
-      <arg type="a(sass)" direction="out"/>
-    </method>
     <method name="Commit">
     </method>
     <property name="Keymap" type="s" access="readwrite"/>
diff --git a/doc/dbus/org.opensuse.Agama1.LocaleMixin.doc.xml b/doc/dbus/org.opensuse.Agama1.LocaleMixin.doc.xml
new file mode 100644
index 0000000000..1f0ae415a3
--- /dev/null
+++ b/doc/dbus/org.opensuse.Agama1.LocaleMixin.doc.xml
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<node name="/org/opensuse/Agama/Manager1">
+  <!--
+      org.opensuse.Agama1.LocaleMixin:
+      @short_description: Included by objects that can localize their output
+  -->
+  <interface name="org.opensuse.Agama1.LocaleMixin">
+    <!--
+        SetLocale:
+        It expects a locale (en_US.UTF-8) as argument.
+    -->
+    <method name="SetLocale">
+      <arg name="locale" direction="in" type="s"/>
+    </method>
+  </interface>
+</node>
diff --git a/doc/dbus/org.opensuse.Agama1.Progress.doc.xml b/doc/dbus/org.opensuse.Agama1.Progress.doc.xml
index 1a1a3ed0e0..02779d19b0 100644
--- a/doc/dbus/org.opensuse.Agama1.Progress.doc.xml
+++ b/doc/dbus/org.opensuse.Agama1.Progress.doc.xml
@@ -26,5 +26,11 @@
         Whether the progress has finished.
     -->
     <property type="b" name="Finished" access="read"/>
+
+    <!--
+        Steps:
+        Known step descriptions.
+    -->
+    <property type="as" name="Steps" access="read"/>
   </interface>
 </node>
diff --git a/doc/dbus/org.opensuse.Agama1.Questions.Generic.doc.xml b/doc/dbus/org.opensuse.Agama1.Questions.Generic.doc.xml
index a58f40cbab..2a0f9ef8bf 100644
--- a/doc/dbus/org.opensuse.Agama1.Questions.Generic.doc.xml
+++ b/doc/dbus/org.opensuse.Agama1.Questions.Generic.doc.xml
@@ -1,6 +1,10 @@
 <!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
  "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
 <node>
+  <!--
+    org.opensuse.Agama1.Questions.Generic:
+    @short_description: Questions from the backend to the user, regular question instance
+  -->
   <interface name="org.opensuse.Agama1.Questions.Generic">
     <!--
         Answer:
diff --git a/doc/dbus/org.opensuse.Agama1.Questions.WithPassword.doc.xml b/doc/dbus/org.opensuse.Agama1.Questions.WithPassword.doc.xml
index 5e93a51921..4ba9c9a029 100644
--- a/doc/dbus/org.opensuse.Agama1.Questions.WithPassword.doc.xml
+++ b/doc/dbus/org.opensuse.Agama1.Questions.WithPassword.doc.xml
@@ -1,6 +1,10 @@
 <!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
  "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
 <node>
+  <!--
+    org.opensuse.Agama1.Questions.WithPassword:
+    @short_description: Questions from the backend to the user, with user provided password response
+  -->
   <interface name="org.opensuse.Agama1.Questions.WithPassword">
     <!--
         Password:
@@ -9,4 +13,3 @@
     <property name="Password" type="s" access="readwrite"/>
   </interface>
 </node>
-
diff --git a/doc/dbus/org.opensuse.Agama1.Questions.doc.xml b/doc/dbus/org.opensuse.Agama1.Questions.doc.xml
index 9e47507d8a..9942832862 100644
--- a/doc/dbus/org.opensuse.Agama1.Questions.doc.xml
+++ b/doc/dbus/org.opensuse.Agama1.Questions.doc.xml
@@ -2,18 +2,19 @@
 "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
 <node>
   <!--
-      org.opensuse.Agama1.Questions:
+org.opensuse.Agama1.Questions:
+@short_description: Questions from the backend to the user, the manager object
 
 Agama offers a mechanism to communicate with clients. The D-Bus service exports a *Questions*
 object that implements the *org.freedesktop.DBus.ObjectManager* interface. Individual questions are
 dynamically exported in a tree under the */org/opensuse/Agama1.Questions* path, for example:
 
-~~~
+<programlisting>
 /org/opensuse/Agama1/Questions
   /org/opensuse/Agama1/Questions/1
   /org/opensuse/Agama1/Questions/2
   /org/opensuse/Agama1/Questions/4
-~~~
+</programlisting>
 
 Each D-Bus question implements its own set of interfaces, depending on the type of question. For
 example, a generic question implements *org.opensuse.Agama.Question1*. And a question asking
@@ -24,18 +25,11 @@ when the question is answered and the answer is successfully read.
   <interface name="org.opensuse.Agama1.Questions">
     <!--
       New:
-      @class: string identifier of the same questions. Useful to identify
-              similar questions asked multiple times or for matching
-              in automatic answers.
+      @class: string identifier of the same questions. Useful to identify similar questions asked multiple times or for matching in automatic answers.
       @text: human string with question text
-      @options: list of possible options that can be used as answer. Example
-                is "OK", "Cancel".
-      @default_option: safe default answer that is used e.g. for focus in UI
-                       or by non-interactive answering. It has to be included
-                       in options parameter.
-      @data: additional data that is specific to given question class. Can be
-             used for additional details about question that helps with UI
-             or with matching automatic answers.
+      @options: list of possible options that can be used as answer. Example is "OK", "Cancel".
+      @default_option: safe default answer that is used e.g. for focus in UI or by non-interactive answering. It has to be included in @options parameter.
+      @data: additional data that is specific to given question class. Can be used for additional details about question that helps with UI or with matching automatic answers.
 
       Creates new generic question.
       Returns the object path of the created question.
@@ -52,18 +46,11 @@ when the question is answered and the answer is successfully read.
 
     <!--
       NewWithPassword:
-      @class: string identifier of the same questions. Useful to identify
-              similar questions asked multiple times or for matching
-              in automatic answers.
+      @class: string identifier of the same questions. Useful to identify similar questions asked multiple times or for matching in automatic answers.
       @text: human string with question text
-      @options: list of possible options that can be used as answer. Example
-                is "OK", "Cancel".
-      @default_option: safe default answer that is used e.g. for focus in UI
-                       or by non-interactive answering. It has to be included
-                       in options parameter.
-      @data: additional data that is specific to given question class. Can be
-             used for additional details about question that helps with UI
-             or with matching automatic answers.
+      @options: list of possible options that can be used as answer. Example is "OK", "Cancel".
+      @default_option: safe default answer that is used e.g. for focus in UI or by non-interactive answering. It has to be included in @options parameter.
+      @data: additional data that is specific to given question class. Can be used for additional details about question that helps with UI or with matching automatic answers.
 
       Creates new question with generic base and additional WithPassword interface.
       Returns the object path of the created question.
@@ -97,6 +84,7 @@ when the question is answered and the answer is successfully read.
       <arg name="path" type="s" direction="in"/>
     </method>
     <!--
+     Interactive:
      property that defines if questions is interactive or automatically answered with
      default answer
      -->
diff --git a/doc/dbus/org.opensuse.Agama1.Registration.doc.xml b/doc/dbus/org.opensuse.Agama1.Registration.doc.xml
index fa510b0eaa..bd87e3ab63 100644
--- a/doc/dbus/org.opensuse.Agama1.Registration.doc.xml
+++ b/doc/dbus/org.opensuse.Agama1.Registration.doc.xml
@@ -1,25 +1,24 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/org/opensuse/Agama/Software1/Product">
   <!--
-    Interface for registering a product.
+    org.opensuse.Agama1.Registration:
+    @short_description: Interface for registering a product.
   -->
   <interface name="org.opensuse.Agama1.Registration">
     <!--
+      Register:
+      @reg_code: Registration code.
+      @result: Result code and description.
+
       Registers the currently selected product.
-    -->
-    <method name="Register">
-      <!--
-        Registration code.
-      -->
-      <arg name="reg_code" direction="in" type="s"/>
-      <!--
+
+      @options are:
+      <programlisting>
         Email s
-      -->
-      <arg name="options" direction="in" type="a{sv}"/>
-      <!--
-        Result code and description.
+      </programlisting>
 
-        Possible result codes are:
+      Possible @result codes are:
+      <programlisting>
         0: success
         1: missing product
         2: already registered
@@ -31,17 +30,21 @@
         8: incorrect credentials
         8: invalid certificate
         10: internal error (e.g., parsing json data)
+      </programlisting>
       -->
+    <method name="Register">
+      <arg name="reg_code" direction="in" type="s"/>
+      <arg name="options" direction="in" type="a{sv}"/>
       <arg name="result" direction="out" type="(us)"/>
     </method>
     <!--
+      Deregister:
+      @result: Result code and description.
+
       Deregisters the currently selected product.
-    -->
-    <method name="Deregister">
-      <!--
-        Result code and description.
 
-        Possible result codes are:
+      Possible result codes are:
+      <programlisting>
         0: success
         1: missing product
         2: not registered yet
@@ -52,24 +55,31 @@
         7: incorrect credentials
         8: invalid certificate
         9: internal error (e.g., parsing json data)
-      -->
+      </programlisting>
+    -->
+    <method name="Deregister">
       <arg name="result" direction="out" type="(us)"/>
     </method>
     <!--
+      RegCode:
       Registration code. Empty if the current product is not registered yet.
     -->
     <property type="s" name="RegCode" access="read"/>
     <!--
+      Email:
       Email used for the registration. Empty if the current product is not registered yet.
       -->
     <property type="s" name="Email" access="read"/>
     <!--
+      Requirement:
       Indicates the registration requirement of the currently selected product.
 
       Possible values:
+      <programlisting>
       0: registration is not required.
       1: registration is optional.
       2: registration is mandatory.
+      </programlisting>
     -->
     <property type="u" name="Requirement" access="read"/>
   </interface>
diff --git a/doc/dbus/refentry-agama.css b/doc/dbus/refentry-agama.css
new file mode 100644
index 0000000000..54efb2e0c6
--- /dev/null
+++ b/doc/dbus/refentry-agama.css
@@ -0,0 +1,19 @@
+body
+{
+  font-family: cantarell, sans-serif;
+}
+@media screen {
+  body
+  {
+    max-width: 60em;
+  }
+}
+@media screen and (min-width: 60em) {
+  /* screen larger than 60em */
+  body { margin: auto; }
+}
+.synopsis, .programlisting {
+	background: rgba(238, 238, 236, 0.5);
+	border: solid 1px rgb(238, 238, 236);
+	padding: 0.5em;
+}
diff --git a/service/lib/agama/dbus/storage/manager.rb b/service/lib/agama/dbus/storage/manager.rb
index 7f96b546b9..ab9c5b4c51 100644
--- a/service/lib/agama/dbus/storage/manager.rb
+++ b/service/lib/agama/dbus/storage/manager.rb
@@ -76,7 +76,7 @@ def initialize(backend, service_status: nil, logger: nil)
           register_iscsi_callbacks
           register_software_callbacks
 
-          add_s390_interfaces if Yast::Arch.s390
+          add_s390_interfaces if Yast::Arch.s390 || ENV["AGAMA_MAINFRAME_COSPLAY"] == "1"
         end
 
         def locale=(locale)
diff --git a/service/lib/agama/storage/dasd/format_operation.rb b/service/lib/agama/storage/dasd/format_operation.rb
index 03d6a2eb85..097c9fcde7 100644
--- a/service/lib/agama/storage/dasd/format_operation.rb
+++ b/service/lib/agama/storage/dasd/format_operation.rb
@@ -20,8 +20,8 @@
 # find current contact information at www.suse.com.
 
 require "yast"
-require "y2s390"
-require "y2s390/format_process"
+require "y2s390" unless ENV["AGAMA_MAINFRAME_COSPLAY"] == "1"
+require "y2s390/format_process" unless ENV["AGAMA_MAINFRAME_COSPLAY"] == "1"
 
 module Agama
   module Storage
diff --git a/service/lib/agama/storage/dasd/manager.rb b/service/lib/agama/storage/dasd/manager.rb
index 8ed847f4ed..91767b2a97 100644
--- a/service/lib/agama/storage/dasd/manager.rb
+++ b/service/lib/agama/storage/dasd/manager.rb
@@ -20,7 +20,7 @@
 # find current contact information at www.suse.com.
 
 require "yast"
-require "y2s390"
+require "y2s390" unless ENV["AGAMA_MAINFRAME_COSPLAY"] == "1"
 require "agama/storage/dasd/enable_operation"
 require "agama/storage/dasd/disable_operation"
 require "agama/storage/dasd/diag_operation"
@@ -53,7 +53,7 @@ class Manager
         # @param logger [Logger, nil]
         def initialize(logger: nil)
           @logger = logger || ::Logger.new($stdout)
-          @devices = Y2S390::DasdsCollection.new([])
+          @devices = Y2S390::DasdsCollection.new([]) unless ENV["AGAMA_MAINFRAME_COSPLAY"] == "1"
 
           @on_probe_callbacks = []
           @on_refresh_callbacks = []
diff --git a/service/lib/agama/storage/zfcp/manager.rb b/service/lib/agama/storage/zfcp/manager.rb
index 354247f682..0594a74706 100644
--- a/service/lib/agama/storage/zfcp/manager.rb
+++ b/service/lib/agama/storage/zfcp/manager.rb
@@ -20,7 +20,7 @@
 # find current contact information at www.suse.com.
 
 require "yast"
-require "y2s390/zfcp"
+require "y2s390/zfcp" unless ENV["AGAMA_MAINFRAME_COSPLAY"] == "1"
 require "y2storage/storage_manager"
 require "agama/storage/zfcp/controller"
 require "agama/storage/zfcp/disk"
diff --git a/setup-services.sh b/setup-services.sh
index 9368ae8578..425f30f726 100755
--- a/setup-services.sh
+++ b/setup-services.sh
@@ -129,6 +129,15 @@ fi
 
 )
 
+# See "Install DocBook tooling" in .github/workflows/github-pages.yml
+# glib2-devel has gdbus-codegen
+$SUDO $ZYPPER install \
+  docbook-xsl-stylesheets \
+  glib2-devel \
+  xmlstarlet \
+  xmlto \
+  || exit 1
+
 # Rust service, CLI and auto-installation.
 
 # Only install cargo if it is not available (avoid conflicts with rustup)
@@ -240,6 +249,10 @@ else
   $SUDO systemctl start NetworkManager
 fi
 
+# Let seed.sh see s390 D-Bus interfaces
+sed -i -e '/^AGAMA_MAINFRAME_COSPLAY=/d' /run/agama/environment.conf
+echo AGAMA_MAINFRAME_COSPLAY=${AGAMA_MAINFRAME_COSPLAY:-0} >> /run/agama/environment.conf
+
 # systemd reload and start of service
 (
   $SUDO systemctl daemon-reload