Merge branch 'master' into issues

.github/workflows/pages-dbus-doc.yml

@@ -0,0 +1,55 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy static content to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: [$default-branch]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Single deploy job since we're just deploying
+  pages_deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Install DocBook tooling
+        run: |
+          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: cd doc/dbus; make diff
+
+      - name: Build HTML via DocBook
+        run: make -C doc
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          # upload the built docs
+          path: 'doc/dist'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

doc/.gitignore

@@ -0,0 +1 @@
+dist/

doc/Makefile

@@ -0,0 +1,4 @@
+all:
+	mkdir -p dist
+	$(MAKE) -C dbus
+	cp index.html dist

doc/dbus/.gitignore

@@ -0,0 +1,2 @@
+tmp/ref-*.xml
+tmp/*.iface.xml

doc/dbus/Makefile

@@ -0,0 +1,50 @@
+distdir=../dist/dbus
+tmpdir=./tmp
+
+# build HTML for GitHub pages
+all: ${distdir} ${tmpdir}
+	for f in org.opensuse.Agama*.doc.xml; do \
+	  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
+	cp index.html ${distdir}
+
+# '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
+
+# check that the implementation and documentation haven't diverged
+# TODO: factor out a script to decouple Make syntax from the rest
+diff: ${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"
+
+${distdir}:
+	mkdir -p $@
+${tmpdir}:
+	mkdir -p $@

doc/dbus/README.md

@@ -0,0 +1,19 @@
+
+
+## File Names
+
+**`*.doc.xml`**: documentation authored by humans in XML comments,
+as specified in [`gdbus-codegen`][gd-cg].
+
+[gd-cg]: https://developer-old.gnome.org/gio/stable/gdbus-codegen.html#id-1.4.25.7.9
+
+`tmp/`**`ref-*.xml`**: intermediate, produced from `*.doc.xml`, contains DocBook
+"**ref**entry"
+
+`../dist/dbus/`**`ref-*.html`**: rendered for publishing on GitHub Pages
+
+`bus/`**`*.bus.xml`**: output of D-Bus introspection
+
+`tmp/`**`*.iface.xml`**: intermediate, simplified `*.doc.xml` and `*.bus.xml`
+to leave the common parts for diffing, see `make diff`.
+

doc/dbus/bus/README.md

@@ -0,0 +1 @@
+FIXME: describe how to maintain these (semi)automatically

doc/dbus/bus/org.opensuse.Agama.Language1.bus.xml

@@ -0,0 +1,39 @@
+<!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/Agama/Language1">
+  <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.freedesktop.DBus.Introspectable">
+    <method name="Introspect">
+      <arg name="xml_data" direction="out" type="s"/>
+    </method>
+  </interface>
+  <interface name="org.opensuse.Agama.Language1">
+    <method name="ToInstall">
+      <arg name="LangIDs" direction="in" type="as"/>
+    </method>
+    <method name="Finish">
+    </method>
+    <property type="a(ssa{sv})" name="AvailableLanguages" access="read"/>
+    <property type="as" name="MarkedForInstall" access="read"/>
+  </interface>
+</node>

doc/dbus/bus/org.opensuse.Agama.Questions1.bus.xml

@@ -0,0 +1,61 @@
+<!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/Agama/Questions1">
+  <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.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.Agama.Questions1">
+    <method name="New">
+      <arg name="text" direction="in" type="s"/>
+      <arg name="options" direction="in" type="as"/>
+      <arg name="default_option" direction="in" type="as"/>
+      <arg name="q" direction="out" type="o"/>
+    </method>
+    <method name="NewLuksActivation">
+      <arg name="device" direction="in" type="s"/>
+      <arg name="label" direction="in" type="s"/>
+      <arg name="size" direction="in" type="s"/>
+      <arg name="attempt" direction="in" type="y"/>
+      <arg name="q" direction="out" type="o"/>
+    </method>
+    <method name="Delete">
+      <arg name="question" direction="in" type="o"/>
+    </method>
+  </interface>
+</node>

doc/dbus/bus/org.opensuse.Agama.Software1.Proposal.bus.xml

@@ -0,0 +1,56 @@
+<!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/Agama/Software1/Proposal">
+  <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.freedesktop.DBus.Introspectable">
+    <method name="Introspect">
+      <arg name="xml_data" direction="out" type="s"/>
+    </method>
+  </interface>
+  <interface name="org.opensuse.Agama.Software1.Proposal">
+    <method name="AddResolvables">
+      <arg name="Id" direction="in" type="s"/>
+      <arg name="Type" direction="in" type="y"/>
+      <arg name="Resolvables" direction="in" type="as"/>
+      <arg name="Optional" direction="in" type="b"/>
+    </method>
+    <method name="GetResolvables">
+      <arg name="Id" direction="in" type="s"/>
+      <arg name="Type" direction="in" type="y"/>
+      <arg name="Optional" direction="in" type="b"/>
+      <arg name="Resolvables" direction="out" type="as"/>
+    </method>
+    <method name="SetResolvables">
+      <arg name="Id" direction="in" type="s"/>
+      <arg name="Type" direction="in" type="y"/>
+      <arg name="Resolvables" direction="in" type="as"/>
+      <arg name="Optional" direction="in" type="b"/>
+    </method>
+    <method name="RemoveResolvables">
+      <arg name="Id" direction="in" type="s"/>
+      <arg name="Type" direction="in" type="y"/>
+      <arg name="Resolvables" direction="in" type="as"/>
+      <arg name="Optional" direction="in" type="b"/>
+    </method>
+  </interface>
+</node>

doc/dbus/bus/org.opensuse.Agama.Software1.bus.xml

@@ -0,0 +1,74 @@
+<!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/Agama/Software1">
+  <node name="Proposal" />
+  <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.freedesktop.DBus.Introspectable">
+    <method name="Introspect">
+      <arg name="xml_data" direction="out" 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"/>
+  </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.Agama1.Validation">
+    <property type="as" name="Errors" access="read"/>
+    <property type="b" name="Valid" access="read"/>
+  </interface>
+  <interface name="org.opensuse.Agama.Software1">
+    <method name="SelectProduct">
+      <arg name="ProductID" direction="in" type="s"/>
+    </method>
+    <method name="ProvisionSelected">
+      <arg name="Provision" direction="in" type="s"/>
+      <arg name="Result" direction="out" type="b"/>
+    </method>
+    <method name="ProvisionsSelected">
+      <arg name="Provisions" direction="in" type="as"/>
+      <arg name="Result" direction="out" type="ab"/>
+    </method>
+    <method name="IsPackageInstalled">
+      <arg name="Name" direction="in" type="s"/>
+      <arg name="Result" direction="out" type="b"/>
+    </method>
+    <method name="UsedDiskSpace">
+      <arg name="SpaceSize" direction="out" type="s"/>
+    </method>
+    <method name="Probe">
+    </method>
+    <method name="Propose">
+    </method>
+    <method name="Install">
+    </method>
+    <method name="Finish">
+    </method>
+    <property type="a(ssa{sv})" name="AvailableBaseProducts" access="read"/>
+    <property type="s" name="SelectedBaseProduct" access="read"/>
+  </interface>
+</node>