diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index de8acf2b8a..330d157d3f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -149,8 +149,8 @@ jobs:
# disable unused repositories to have faster refresh
run: zypper modifyrepo -d repo-non-oss repo-openh264 repo-update && ( zypper ref || zypper ref || zypper ref )
- - name: Install Ruby development files
- run: zypper --non-interactive install gcc gcc-c++ make openssl-devel ruby-devel npm augeas-devel
+ - name: Install Ruby development files and XML tooling
+ run: zypper --non-interactive install gcc gcc-c++ make openssl-devel ruby-devel npm augeas-devel xmlstarlet
- name: Install RubyGems dependencies
run: bundle config set --local with 'development' && bundle install
@@ -158,6 +158,10 @@ jobs:
- name: Generate doc
run: bundle exec yardoc --fail-on-warning
+ - name: Check that introspected API and its docs have not diverged
+ run: make -C ../doc check
+
+
integration-tests:
timeout-minutes: 60
runs-on: ubuntu-latest
diff --git a/.github/workflows/github-pages.yml b/.github/workflows/github-pages.yml
index 4516c94e4c..9d3c6505b0 100644
--- a/.github/workflows/github-pages.yml
+++ b/.github/workflows/github-pages.yml
@@ -38,9 +38,6 @@ jobs:
sudo apt-get update
sudo apt-get --assume-yes --no-install-recommends install xmlto docbook-xsl xmlstarlet
- - name: Check that introspected API and its docs have not diverged
- run: make -C doc check
-
- name: Build HTML via DocBook
run: make -C doc
diff --git a/doc/Makefile b/doc/Makefile
index 0f43bebada..e704a15195 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -6,4 +6,4 @@ all:
cp index.html dist
check:
- $(MAKE) -C dbus diff
+ $(MAKE) -C dbus check
diff --git a/doc/dbus/Makefile b/doc/dbus/Makefile
index a37a0506f6..7195475146 100644
--- a/doc/dbus/Makefile
+++ b/doc/dbus/Makefile
@@ -23,7 +23,8 @@ SHELL=/bin/bash
# check that the implementation and documentation haven't diverged
# TODO: factor out a script to decouple Make syntax from the rest
-diff: ${tmpdir}
+diff: check
+check: ${tmpdir}
ALL_GOOD=true; \
for doc_xml in org.opensuse.Agama*.doc.xml; do \
IFACE=$${doc_xml%.doc.xml}; \
diff --git a/doc/dbus/bus/README.md b/doc/dbus/bus/README.md
index 13d361c517..36328c2abe 100644
--- a/doc/dbus/bus/README.md
+++ b/doc/dbus/bus/README.md
@@ -1 +1,22 @@
-FIXME: describe how to maintain these (semi)automatically
+The `*.bus.xml` files here are produced by introspecting actual objects
+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.
+
+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
+`org.freedesktop.DBus.*` filenames, we don't need to document those interfaces)
+
+The interfaces implemented in Rust already have documentation in them
+(courtesy of Rust macro magic) but it is not in the exact format that
+`gdbus-codegen` understands :sob:.
+
+You are expected to copy a new `foo.bus.xml` to `../foo.doc.xml`, remove the
+`` elements other than `foo`, and add meaningful documentation.
+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?
diff --git a/doc/dbus/bus/org.opensuse.Agama.Locale1.bus.xml b/doc/dbus/bus/org.opensuse.Agama.Locale1.bus.xml
index b3b346f936..b8a0dfb0c7 100644
--- a/doc/dbus/bus/org.opensuse.Agama.Locale1.bus.xml
+++ b/doc/dbus/bus/org.opensuse.Agama.Locale1.bus.xml
@@ -2,10 +2,29 @@
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
+
-
-
-
-
-
-
-
+
diff --git a/doc/dbus/bus/org.opensuse.Agama.Questions1.LuksActivation.bus.xml b/doc/dbus/bus/org.opensuse.Agama.Questions1.LuksActivation.bus.xml
index 12d742ebde..4443ec2189 100644
--- a/doc/dbus/bus/org.opensuse.Agama.Questions1.LuksActivation.bus.xml
+++ b/doc/dbus/bus/org.opensuse.Agama.Questions1.LuksActivation.bus.xml
@@ -1,41 +1,53 @@
+
-
+ "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-
-
+
+
+
-
-
-
+
+
+
-
-
+
+
+
-
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
diff --git a/doc/dbus/bus/org.opensuse.Agama.Questions1.bus.xml b/doc/dbus/bus/org.opensuse.Agama.Questions1.bus.xml
index 53ba763367..4f27c734c5 100644
--- a/doc/dbus/bus/org.opensuse.Agama.Questions1.bus.xml
+++ b/doc/dbus/bus/org.opensuse.Agama.Questions1.bus.xml
@@ -1,61 +1,91 @@
+
-
-
-
-
-
-
+ "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+
+
+
-
-
-
-
-
-
-
-
+
+
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
+
+
-
+
+
-
+
-
-
-
-
-
-
+
+
+
+
+
-
-
-
-
-
-
+
+
+
+
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/doc/dbus/bus/org.opensuse.Agama.Storage1.ZFCP.Manager.bus.xml b/doc/dbus/bus/org.opensuse.Agama.Storage1.ZFCP.Manager.bus.xml
new file mode 100644
index 0000000000..f959f913bc
--- /dev/null
+++ b/doc/dbus/bus/org.opensuse.Agama.Storage1.ZFCP.Manager.bus.xml
@@ -0,0 +1,9 @@
+
+
+
+
+
+
+
+
diff --git a/doc/dbus/bus/org.opensuse.Agama1.Manager.bus.xml b/doc/dbus/bus/org.opensuse.Agama1.Manager.bus.xml
index 135f5d530d..ff8365b815 100644
--- a/doc/dbus/bus/org.opensuse.Agama1.Manager.bus.xml
+++ b/doc/dbus/bus/org.opensuse.Agama1.Manager.bus.xml
@@ -48,8 +48,11 @@
+
+
+
diff --git a/doc/dbus/bus/seed.sh b/doc/dbus/bus/seed.sh
index 570d248502..51f6885ce5 100755
--- a/doc/dbus/bus/seed.sh
+++ b/doc/dbus/bus/seed.sh
@@ -22,17 +22,21 @@ look Software1.Proposal
look Storage1
look Users1
+abusctl introspect --xml-interface \
+ ${DD}.Questions1 \
+ ${SS}/Questions1 \
+ | sed -e '/ ${DD}.Questions1.bus.xml
+# ^ remove detailed introspection of subnodes
+
abusctl call \
${DD}.Questions1 \
${SS}/Questions1 \
${DD}.Questions1 \
New sasas "should I stay or should I go" 2 yes no 1 yes
-# FIXME: the ruby code talks about a Generic interface but then
-# we end up declaring the properties on org.opensuse.Agama.Questions1
-# which is the same as what the factory object uses. WTF.
abusctl introspect --xml-interface \
${DD}.Questions1 \
- ${SS}/Questions1/1 \
+ ${SS}/Questions1/0 \
> ${DD}.Questions1.Generic.bus.xml
abusctl call \
@@ -42,5 +46,5 @@ abusctl call \
NewLuksActivation sssy "/dev/tape1" "ZX Spectrum games" "90 minutes" 1
abusctl introspect --xml-interface \
${DD}.Questions1 \
- ${SS}/Questions1/2 \
+ ${SS}/Questions1/1 \
> ${DD}.Questions1.LuksActivation.bus.xml
diff --git a/doc/dbus/make-index b/doc/dbus/make-index
index 9f9df4cfbe..4c97fe442e 100755
--- a/doc/dbus/make-index
+++ b/doc/dbus/make-index
@@ -1,5 +1,6 @@
#!/bin/sh
echo ""
+echo "Agama D-Bus API"
echo ""
for F in tmp/ref-*.xml; do
F=${F#tmp/}
@@ -8,3 +9,4 @@ for F in tmp/ref-*.xml; do
echo " >${F#ref-}"
done
echo "
"
+echo "up"
diff --git a/doc/dbus/org.opensuse.Agama.Questions1.Generic.doc.xml b/doc/dbus/org.opensuse.Agama.Questions1.Generic.doc.xml
new file mode 100644
index 0000000000..8d6f667341
--- /dev/null
+++ b/doc/dbus/org.opensuse.Agama.Questions1.Generic.doc.xml
@@ -0,0 +1,35 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/doc/dbus/org.opensuse.Agama.Questions1.LuksActivation.doc.xml b/doc/dbus/org.opensuse.Agama.Questions1.LuksActivation.doc.xml
new file mode 100644
index 0000000000..3473a7c5ce
--- /dev/null
+++ b/doc/dbus/org.opensuse.Agama.Questions1.LuksActivation.doc.xml
@@ -0,0 +1,19 @@
+
+
+
+
+
+
+
+
+
+
+
diff --git a/doc/dbus/org.opensuse.Agama.Questions1.doc.xml b/doc/dbus/org.opensuse.Agama.Questions1.doc.xml
index fb75d766ba..16d4bb24ca 100644
--- a/doc/dbus/org.opensuse.Agama.Questions1.doc.xml
+++ b/doc/dbus/org.opensuse.Agama.Questions1.doc.xml
@@ -1,6 +1,6 @@
-
+
+
+
+
+
+
+
diff --git a/doc/dbus/org.opensuse.Agama.Storage1.doc.xml b/doc/dbus/org.opensuse.Agama.Storage1.doc.xml
index 83cbc012bb..2a51000dd2 100644
--- a/doc/dbus/org.opensuse.Agama.Storage1.doc.xml
+++ b/doc/dbus/org.opensuse.Agama.Storage1.doc.xml
@@ -1,6 +1,8 @@
+
+
@@ -20,15 +22,4 @@
-->
-
-
-
-
-
-
-
diff --git a/doc/dbus/org.opensuse.Agama1.Manager.doc.xml b/doc/dbus/org.opensuse.Agama1.Manager.doc.xml
index f25653fdb3..02a8009499 100644
--- a/doc/dbus/org.opensuse.Agama1.Manager.doc.xml
+++ b/doc/dbus/org.opensuse.Agama1.Manager.doc.xml
@@ -13,6 +13,8 @@
+
+
+
+
-#### Properties
-
-- Id -> unsigned 32-bit integer (r)
- Question id. The question is exported at *root_path/id*.
-
-- Text -> string (r)
- Text of the question. Clients show this text to the users.
-
-- Options -> array(string) (r)
- Options for answering the question. The question only admits an option from the list as valid
- answer.
-
-- DefaultOption -> string (r)
- Clients should offer this option as default option for answering the question.
-
-- Answer -> string (rw)
- Answer for the question. Clients set an option as answer.
-
-### org.opensuse.Agama.Questions1.LuksActivation
-
-#### Properties
-
-- Password -> string (rw)
- Password provided to decrypt a LUKS device.
-
-- Attempt -> unsigned 32-bit integer (r)
- Current attempt to decrypt the device. This value is useful for clients to know if the very same
- question is asked again (i.e., when the provided password did not work).
-
## Manager
See the new-style [reference][mgr-ref] ([source][mgr-src]).