Merge branch 'xml-docs' into 'main'

Include the documentation from the DBus interfaces in the devel-docs

See merge request GNOME/at-spi2-core!121

10 files changed, 100 insertions, 24 deletions

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index e959de65..f4514eb2 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -184,11 +184,11 @@ reference:
     MESON_EXTRA_FLAGS: "--buildtype=release -Ddocs=true"
   script:
     - meson setup ${MESON_EXTRA_FLAGS} --prefix /usr _build .
-    - ninja -C _build doc/atk doc/libatspi devel-docs/devel-docs
+    - ninja -C _build doc/atk doc/libatspi devel-docs/html
     - mkdir _reference
     - mv _build/doc/libatspi _reference/libatspi
     - mv _build/doc/atk _reference/atk
-    - mv _build/devel-docs/devel-docs  _reference/devel-docs
+    - mv _build/devel-docs/html  _reference/devel-docs
   artifacts:
     paths:
       - _reference
diff --git a/atk/atkutil.h b/atk/atkutil.h
index c7ad75ad..844fe2a1 100644
--- a/atk/atkutil.h
+++ b/atk/atkutil.h
@@ -87,9 +87,6 @@ typedef gint (*AtkKeySnoopFunc) (AtkKeyEventStruct *event,
 
 /**
  * AtkKeyEventStruct:
- *
- * Encapsulates information about a key event.
- *
  * @type: An AtkKeyEventType, generally one of ATK_KEY_EVENT_PRESS or ATK_KEY_EVENT_RELEASE
  * @state: A bitmask representing the state of the modifier keys immediately after the event takes place.
  * The meaning of the bits is currently defined to match the bitmask used by GDK in
@@ -106,6 +103,8 @@ typedef gint (*AtkKeySnoopFunc) (AtkKeyEventStruct *event,
  * @timestamp: A timestamp in milliseconds indicating when the event occurred.
  * These timestamps are relative to a starting point which should be considered arbitrary,
  * and only used to compare the dispatch times of events to one another.
+ *
+ * Encapsulates information about a key event.
  **/
 struct _AtkKeyEventStruct
 {
diff --git a/atspi/atspi-constants.h b/atspi/atspi-constants.h
index bb9ae543..9d464cc9 100644
--- a/atspi/atspi-constants.h
+++ b/atspi/atspi-constants.h
@@ -84,14 +84,14 @@
 
  */
 
+#ifndef _ATSPI_CONSTANTS_H_
+#define _ATSPI_CONSTANTS_H_
 /**
  * AtspiConstants:
  *
  * Constant definitions needed by multiple interfaces.
  */
 
-#ifndef _ATSPI_CONSTANTS_H_
-#define _ATSPI_CONSTANTS_H_
 #ifdef __cplusplus
 extern "C"
 {
diff --git a/atspi/atspi-types.h b/atspi/atspi-types.h
index cb762616..4486b584 100644
--- a/atspi/atspi-types.h
+++ b/atspi/atspi-types.h
@@ -140,7 +140,6 @@ typedef struct _AtspiKeySet
 
 /**
  * AtspiKeyListenerSyncType:
- *
  * @ATSPI_KEYLISTENER_NOSYNC: Events may be delivered asynchronously,
  * which means in some cases they may already have been delivered to the
  * application before the AT client receives the notification.
diff --git a/ci/container_builds.yml b/ci/container_builds.yml
index 564e614f..dea74b3d 100644
--- a/ci/container_builds.yml
+++ b/ci/container_builds.yml
@@ -13,7 +13,7 @@ include:
 variables:
   # When branching change the suffix to avoid conflicts with images
   # from the main branch
-  BASE_TAG: "2022-12-09.1-main"
+  BASE_TAG: "2022-12-13.3-main"
   RUST_STABLE: "1.64.0"
 
 .container.opensuse@x86_64:
@@ -68,7 +68,7 @@ opensuse-container@x86_64:
   stage: "container-build"
   variables:
     FDO_DISTRIBUTION_TAG: "x86_64-${BASE_TAG}"
-    FDO_DISTRIBUTION_VERSION: "35"
+    FDO_DISTRIBUTION_VERSION: "37"
     FDO_UPSTREAM_REPO: "gnome/at-spi2-core"
     FDO_DISTRIBUTION_PACKAGES: >-
       clang
@@ -90,10 +90,13 @@ opensuse-container@x86_64:
       libasan
       libxkbcommon-devel
       libxml2-devel
-      meson
+      ninja-build
       procps
-      python38
+      python3
+      python3-pip
       systemd-devel
+    FDO_DISTRIBUTION_EXEC: >-
+      pip3 install meson==0.64
 
 fedora-container@x86_64:
   extends:
diff --git a/devel-docs/conf.py b/devel-docs/conf.py
index 8b371a56..36bd9181 100644
--- a/devel-docs/conf.py
+++ b/devel-docs/conf.py
@@ -14,6 +14,8 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+import os
+
 
 # -- Project information -----------------------------------------------------
 
@@ -38,7 +40,6 @@ templates_path = ['_templates']
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
-
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
diff --git a/devel-docs/index.rst b/devel-docs/index.rst
index 8e34027b..62bc78ee 100644
--- a/devel-docs/index.rst
+++ b/devel-docs/index.rst
@@ -8,6 +8,7 @@ Development guide for the accessibility infrastructure
    roadmap
    toolkits
    xml-changes
+   xml-interfaces
    :maxdepth: 1
    :caption: Contents:
 
@@ -26,6 +27,7 @@ General documentation
 - :doc:`roadmap`
 - :doc:`toolkits`
 - :doc:`xml-changes`
+- :doc:`xml-interfaces`
 
 Refactoring and cleanup
 -----------------------
diff --git a/devel-docs/meson.build b/devel-docs/meson.build
index d8978fcc..b405df4f 100644
--- a/devel-docs/meson.build
+++ b/devel-docs/meson.build
@@ -6,37 +6,79 @@ sphinx_build = find_program('sphinx-build',
                             native: true,
                             required: get_option('docs'))
 
-interfaces_rst_sources = []
+# Gather the XML files, prefixed by the "xml/" directory name
+# introspection_sources comes from xml/meson.build
 interfaces_xml = []
-
 foreach i: introspection_sources
-  # /foo/bar/baz.xml -> doc-baz.rst
-  doc_name = 'doc-' + fs.replace_suffix(fs.name(i), '.rst')
-  interfaces_rst_sources += doc_name
-
   interfaces_xml += join_paths(meson.project_source_root(), 'xml', i)
 endforeach
 
+# gdbus-codegen can take an dbus.xml file and generate various interfaces
+# from it, named as some_prefix-org.foo.InterfaceName.rst
+# We need an explicit list of those; for example, xml/Event.xml contains
+# various interfaces and so we can't just substitute "xml" for "rst".
+interfaces_rst_sources = [
+  'doc-org.a11y.atspi.Accessible.rst',
+  'doc-org.a11y.atspi.Action.rst',
+  'doc-org.a11y.atspi.Application.rst',
+  'doc-org.a11y.atspi.Cache.rst',
+  'doc-org.a11y.atspi.Collection.rst',
+  'doc-org.a11y.atspi.Component.rst',
+  'doc-org.a11y.atspi.DeviceEventController.rst',
+  'doc-org.a11y.atspi.DeviceEventListener.rst',
+  'doc-org.a11y.atspi.Document.rst',
+  'doc-org.a11y.atspi.EditableText.rst',
+  'doc-org.a11y.atspi.Event.Document.rst',
+  'doc-org.a11y.atspi.Event.Focus.rst',
+  'doc-org.a11y.atspi.Event.Keyboard.rst',
+  'doc-org.a11y.atspi.Event.Mouse.rst',
+  'doc-org.a11y.atspi.Event.Object.rst',
+  'doc-org.a11y.atspi.Event.Terminal.rst',
+  'doc-org.a11y.atspi.Event.Window.rst',
+  'doc-org.a11y.atspi.Hyperlink.rst',
+  'doc-org.a11y.atspi.Hypertext.rst',
+  'doc-org.a11y.atspi.Image.rst',
+  'doc-org.a11y.atspi.Registry.rst',
+  'doc-org.a11y.atspi.Selection.rst',
+  'doc-org.a11y.atspi.Socket.rst',
+  'doc-org.a11y.atspi.Table.rst',
+  'doc-org.a11y.atspi.TableCell.rst',
+  'doc-org.a11y.atspi.Text.rst',
+  'doc-org.a11y.atspi.Value.rst',
+]
+
+# The 'devel-docs/doc' here is a prefix that gdbus-codegen will put in front
+# of the interface names that it finds in the input XML files.
 interfaces_rst = custom_target(
   'interfaces_rst',
   input: interfaces_xml,
   output: interfaces_rst_sources,
-  command: [ gdbus_codegen, '--generate-rst', 'doc', '@INPUT@']
+  command: [ gdbus_codegen, '--generate-rst', 'devel-docs/doc', '@INPUT@']
 )
 
 docs_sources = [
   'atk-deprecations.rst',
+  'conf.py',
   'de-controller.rst',
   'gitlab-ci.rst',
   'index.rst',
   'roadmap.rst',
   'toolkits.rst',
   'xml-changes.rst',
+  'xml-interfaces.rst',
 ]
 
+# sphinx-build(1) does not seem to easily support generated files in the build directory.
+# So, we'll copy all the source files from the source directory to the build directory,
+# and just do the build from there.
+copied_docs_sources = []
+foreach i: docs_sources
+  copied_docs_sources += fs.copyfile(i)
+endforeach
+
 custom_target(
   'devel_docs',
-  input: docs_sources + interfaces_rst,
-  output: 'devel-docs',
-  command: [ sphinx_build, meson.current_source_dir(), '@OUTPUT@' ],
+  input: copied_docs_sources + interfaces_rst,
+  output: 'html',
+  command: [ sphinx_build, meson.current_build_dir(), '@OUTPUT@' ],
 )
diff --git a/devel-docs/xml-interfaces.rst b/devel-docs/xml-interfaces.rst
new file mode 100644
index 00000000..447aa4a4
--- /dev/null
+++ b/devel-docs/xml-interfaces.rst
@@ -0,0 +1,30 @@
+DBus XML Interfaces
+===================
+
+* :doc:`doc-org.a11y.atspi.Accessible`
+* :doc:`doc-org.a11y.atspi.Action`
+* :doc:`doc-org.a11y.atspi.Application`
+* :doc:`doc-org.a11y.atspi.Cache`
+* :doc:`doc-org.a11y.atspi.Collection`
+* :doc:`doc-org.a11y.atspi.Component`
+* :doc:`doc-org.a11y.atspi.DeviceEventController`
+* :doc:`doc-org.a11y.atspi.DeviceEventListener`
+* :doc:`doc-org.a11y.atspi.Document`
+* :doc:`doc-org.a11y.atspi.EditableText`
+* :doc:`doc-org.a11y.atspi.Event.Document`
+* :doc:`doc-org.a11y.atspi.Event.Focus`
+* :doc:`doc-org.a11y.atspi.Event.Keyboard`
+* :doc:`doc-org.a11y.atspi.Event.Mouse`
+* :doc:`doc-org.a11y.atspi.Event.Object`
+* :doc:`doc-org.a11y.atspi.Event.Terminal`
+* :doc:`doc-org.a11y.atspi.Event.Window`
+* :doc:`doc-org.a11y.atspi.Hyperlink`
+* :doc:`doc-org.a11y.atspi.Hypertext`
+* :doc:`doc-org.a11y.atspi.Image`
+* :doc:`doc-org.a11y.atspi.Registry`
+* :doc:`doc-org.a11y.atspi.Selection`
+* :doc:`doc-org.a11y.atspi.Socket`
+* :doc:`doc-org.a11y.atspi.Table`
+* :doc:`doc-org.a11y.atspi.TableCell`
+* :doc:`doc-org.a11y.atspi.Text`
+* :doc:`doc-org.a11y.atspi.Value`
diff --git a/meson.build b/meson.build
index b386aa29..28a13853 100644
--- a/meson.build
+++ b/meson.build
@@ -6,7 +6,7 @@ project('at-spi2-core', 'c',
           'warning_level=1',
           'c_std=c99',
         ],
-        meson_version: '>= 0.60.0')
+        meson_version: '>= 0.64.0')
 
 add_project_arguments([ '-D_POSIX_C_SOURCE=200809L', '-D_DEFAULT_SOURCE' ], language: 'c')