From d5ec0866a6b023c8115ad443663faa3a13bc4053 Mon Sep 17 00:00:00 2001 From: Martin Vidner Date: Wed, 14 Jun 2023 13:33:53 +0200 Subject: [PATCH 1/9] doc/dbus/bus: update .bus.xml uninteresting changes: - Locale1 now includes Peer and Properties --- .../bus/org.opensuse.Agama.Locale1.bus.xml | 37 +++++++++++++++++-- 1 file changed, 34 insertions(+), 3 deletions(-) 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..f80d0e443c 100644 --- a/doc/dbus/bus/org.opensuse.Agama.Questions1.LuksActivation.bus.xml +++ b/doc/dbus/bus/org.opensuse.Agama.Questions1.LuksActivation.bus.xml @@ -1,32 +1,42 @@ - + "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"> + + + + + + + + + + + + + - - - + + + - - - + + + - - + + + - + - - - - - @@ -35,7 +45,8 @@ - - + + + diff --git a/doc/dbus/bus/org.opensuse.Agama.Questions1.bus.xml b/doc/dbus/bus/org.opensuse.Agama.Questions1.bus.xml index 53ba763367..1b0b5f6894 100644 --- a/doc/dbus/bus/org.opensuse.Agama.Questions1.bus.xml +++ b/doc/dbus/bus/org.opensuse.Agama.Questions1.bus.xml @@ -29,14 +29,23 @@ - + + - + + - + 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 From 2055399008396dbd7b0a0bda978e523a9801bd23 Mon Sep 17 00:00:00 2001 From: Martin Vidner Date: Wed, 14 Jun 2023 14:21:58 +0200 Subject: [PATCH 3/9] doc/dbus/bus: Questions1.Generic now properly declared --- ....opensuse.Agama.Questions1.Generic.bus.xml | 17 ++-- ...se.Agama.Questions1.LuksActivation.bus.xml | 15 +-- .../bus/org.opensuse.Agama.Questions1.bus.xml | 95 +++++++++++-------- ....opensuse.Agama.Questions1.Generic.doc.xml | 12 +++ ...se.Agama.Questions1.LuksActivation.doc.xml | 9 ++ .../org.opensuse.Agama.Questions1.doc.xml | 6 +- 6 files changed, 99 insertions(+), 55 deletions(-) create mode 100644 doc/dbus/org.opensuse.Agama.Questions1.Generic.doc.xml create mode 100644 doc/dbus/org.opensuse.Agama.Questions1.LuksActivation.doc.xml diff --git a/doc/dbus/bus/org.opensuse.Agama.Questions1.Generic.bus.xml b/doc/dbus/bus/org.opensuse.Agama.Questions1.Generic.bus.xml index e9223f2171..44e8169cb6 100644 --- a/doc/dbus/bus/org.opensuse.Agama.Questions1.Generic.bus.xml +++ b/doc/dbus/bus/org.opensuse.Agama.Questions1.Generic.bus.xml @@ -33,16 +33,17 @@ + + + + + + + - + - - - - - - - + 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 f80d0e443c..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,3 +1,4 @@ + @@ -13,6 +14,13 @@ + + + + + + + @@ -37,13 +45,6 @@ - - - - - - - diff --git a/doc/dbus/bus/org.opensuse.Agama.Questions1.bus.xml b/doc/dbus/bus/org.opensuse.Agama.Questions1.bus.xml index 1b0b5f6894..4f27c734c5 100644 --- a/doc/dbus/bus/org.opensuse.Agama.Questions1.bus.xml +++ b/doc/dbus/bus/org.opensuse.Agama.Questions1.bus.xml @@ -1,30 +1,39 @@ + - - - - - - - - - - - + "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"> + + + - - - + + - - - - - - - - + + + + + + + + + + + + + + + + + + + @@ -49,22 +58,34 @@ - - - - - - + + + + + - - - - - - + + + + - - + + + + + + + + + + + + + + + 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..7f6c753dc7 --- /dev/null +++ b/doc/dbus/org.opensuse.Agama.Questions1.Generic.doc.xml @@ -0,0 +1,12 @@ + + + + + + + + + + + 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..6e021a732d --- /dev/null +++ b/doc/dbus/org.opensuse.Agama.Questions1.LuksActivation.doc.xml @@ -0,0 +1,9 @@ + + + + + + + + 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 @@ --> - - - - - - - From f966dfcfcfd63cb3cd2c6f1dadf076bf5dea1cf7 Mon Sep 17 00:00:00 2001 From: Martin Vidner Date: Wed, 14 Jun 2023 15:17:22 +0200 Subject: [PATCH 6/9] doc: make check: move it to backend_doc CI job that runs in all branches --- .github/workflows/ci.yml | 8 ++++++-- .github/workflows/github-pages.yml | 3 --- doc/Makefile | 2 +- doc/dbus/Makefile | 3 ++- 4 files changed, 9 insertions(+), 7 deletions(-) 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}; \ From 1a5f036446a8ad1865c4ab626130ae906d38cdd5 Mon Sep 17 00:00:00 2001 From: Martin Vidner Date: Wed, 14 Jun 2023 15:40:41 +0200 Subject: [PATCH 7/9] doc/dbus: Questions1.Generic and .LuksActivation moved from dbus_api.md --- ....opensuse.Agama.Questions1.Generic.doc.xml | 25 ++++++++++++- ...se.Agama.Questions1.LuksActivation.doc.xml | 10 +++++ doc/dbus_api.md | 37 ------------------- 3 files changed, 34 insertions(+), 38 deletions(-) diff --git a/doc/dbus/org.opensuse.Agama.Questions1.Generic.doc.xml b/doc/dbus/org.opensuse.Agama.Questions1.Generic.doc.xml index 7f6c753dc7..8d6f667341 100644 --- a/doc/dbus/org.opensuse.Agama.Questions1.Generic.doc.xml +++ b/doc/dbus/org.opensuse.Agama.Questions1.Generic.doc.xml @@ -2,11 +2,34 @@ "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"> + + + + + + + + + - diff --git a/doc/dbus/org.opensuse.Agama.Questions1.LuksActivation.doc.xml b/doc/dbus/org.opensuse.Agama.Questions1.LuksActivation.doc.xml index 6e021a732d..3473a7c5ce 100644 --- a/doc/dbus/org.opensuse.Agama.Questions1.LuksActivation.doc.xml +++ b/doc/dbus/org.opensuse.Agama.Questions1.LuksActivation.doc.xml @@ -2,7 +2,17 @@ "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"> + + + diff --git a/doc/dbus_api.md b/doc/dbus_api.md index 531f6936d8..b351b01067 100644 --- a/doc/dbus_api.md +++ b/doc/dbus_api.md @@ -635,43 +635,6 @@ See the new-style [reference][usr-ref] ([source][usr-src]). [usr-ref]: https://opensuse.github.io/agama/dbus/ref-org.opensuse.Agama.Users1.html [usr-src]: dbus/org.opensuse.Agama.Users1.doc.xml -## Questions - - -### org.opensuse.Agama.Questions1 - - -#### 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]). From 367bade42c7e94723362fe0c928fd512d3bc72bf Mon Sep 17 00:00:00 2001 From: Martin Vidner Date: Thu, 15 Jun 2023 10:53:20 +0200 Subject: [PATCH 8/9] doc/dbus: better bus/README.md [skip CI] --- doc/dbus/bus/README.md | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) 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? From dab1e5bd31a98ec75c0f6815c9b6f66e1fc091a7 Mon Sep 17 00:00:00 2001 From: Martin Vidner Date: Thu, 15 Jun 2023 11:04:13 +0200 Subject: [PATCH 9/9] doc/dbus: add title to make-index --- doc/dbus/make-index | 2 ++ 1 file changed, 2 insertions(+) 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"