Convert all the devel-docs files to reStructuredText

Sphinx, the document generator, more or less prefers this format.

10 files changed, 538 insertions, 494 deletions

diff --git a/devel-docs/atk-deprecations.md b/devel-docs/atk-deprecations.md
deleted file mode 100644
index cf411cd4..00000000
--- a/devel-docs/atk-deprecations.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# Deprecations in ATK that need work elsewhere
-
-`atk_document_get_locale()` and the corresponding field in the vtable
-`AtkDocumentIface.get_document_locale` are documented as deprecated since 2013 (commit
-97880727).  However, WebKitGtk still seems to implement it; it should use
-`AtkObjectClass.get_object_locale` instead.
-
-Note that Orca does not seem to use the `Document.GetLocale` method nor the
-`Accessible.Locale` property, so probably the code above from WebKitGtk is not exercised.
-
-## AtkValue
-
-The following methods are deprecated in `AtkValueIface` since 2014 (commit 98838b2a):
-
-* `get_current_value` - replaced with `get_value_and_text`
-* `set_current_value` - replaced with `set_value`
-
-And the following are replaced with `get_range`, which returns an `AtkRange` boxed type:
-
-* `get_maximum_value`
-* `get_minimum_value`
-* `get_minimum_increment`
-
-Firefox still does not implement `get_range`, `get_value_and_text`, `set_value`.  See bug #71.
diff --git a/devel-docs/atk-deprecations.rst b/devel-docs/atk-deprecations.rst
new file mode 100644
index 00000000..53ad6821
--- /dev/null
+++ b/devel-docs/atk-deprecations.rst
@@ -0,0 +1,31 @@
+Deprecations in ATK that need work elsewhere
+============================================
+
+``atk_document_get_locale()`` and the corresponding field in the vtable
+``AtkDocumentIface.get_document_locale`` are documented as deprecated
+since 2013 (commit 97880727). However, WebKitGtk still seems to
+implement it; it should use ``AtkObjectClass.get_object_locale``
+instead.
+
+Note that Orca does not seem to use the ``Document.GetLocale`` method
+nor the ``Accessible.Locale`` property, so probably the code above from
+WebKitGtk is not exercised.
+
+AtkValue
+--------
+
+The following methods are deprecated in ``AtkValueIface`` since 2014
+(commit 98838b2a):
+
+-  ``get_current_value`` - replaced with ``get_value_and_text``
+-  ``set_current_value`` - replaced with ``set_value``
+
+And the following are replaced with ``get_range``, which returns an
+``AtkRange`` boxed type:
+
+-  ``get_maximum_value``
+-  ``get_minimum_value``
+-  ``get_minimum_increment``
+
+Firefox still does not implement ``get_range``, ``get_value_and_text``,
+``set_value``. See bug #71.
diff --git a/devel-docs/de-controller.md b/devel-docs/de-controller.md
deleted file mode 100644
index 000b92f4..00000000
--- a/devel-docs/de-controller.md
+++ /dev/null
@@ -1,29 +0,0 @@
-Notes on the device event controller machinery
-----------------------------------------------
-
-In pyatspi2, `Registry.setReferenceWIndow()` is misspelled.  However,
-that function is never called in Orca or elsewhere, as far as I can
-tell.
-
-This ties down to `atspi_registry_set_reference_window()`, which just
-calls `_atspi_mutter_set_reference_window()`.  The side effect of that
-is to set the `ATSPI_MUTTER_DATA.window_id` and
-`window_id_is_explicit`, but again, those fields never get used in the
-`atspi-mutter.c` code.  I think they were meant to be used in
-`_atspi_mutter_generate_keyboard_event` or
-`_atspi_mutter_generate_mouse_event`.
-
-Relatedly, `_atspi_mutter_generate_keyboard_event` takes a `keystring`
-argument but it's not used.
-
-What is incomplete here?
-
-Refactoring plan
-----------------
-
-While the device event controller (DEC) code works for X11, it doesn't
-work for Wayland because there are no hooks there to sniff the
-keyboard or mouse.
-
-However, the machinery to synthesize events is presumably still
-useful.  I'd like to be able to add tests for it.
diff --git a/devel-docs/de-controller.rst b/devel-docs/de-controller.rst
new file mode 100644
index 00000000..ee1d6f95
--- /dev/null
+++ b/devel-docs/de-controller.rst
@@ -0,0 +1,29 @@
+Notes on the device event controller machinery
+----------------------------------------------
+
+In pyatspi2, ``Registry.setReferenceWIndow()`` is misspelled. However,
+that function is never called in Orca or elsewhere, as far as I can
+tell.
+
+This ties down to ``atspi_registry_set_reference_window()``, which just
+calls ``_atspi_mutter_set_reference_window()``. The side effect of that
+is to set the ``ATSPI_MUTTER_DATA.window_id`` and
+``window_id_is_explicit``, but again, those fields never get used in the
+``atspi-mutter.c`` code. I think they were meant to be used in
+``_atspi_mutter_generate_keyboard_event`` or
+``_atspi_mutter_generate_mouse_event``.
+
+Relatedly, ``_atspi_mutter_generate_keyboard_event`` takes a
+``keystring`` argument but it’s not used.
+
+What is incomplete here?
+
+Refactoring plan
+----------------
+
+While the device event controller (DEC) code works for X11, it doesn’t
+work for Wayland because there are no hooks there to sniff the keyboard
+or mouse.
+
+However, the machinery to synthesize events is presumably still useful.
+I’d like to be able to add tests for it.
diff --git a/devel-docs/gitlab-ci.md b/devel-docs/gitlab-ci.md
deleted file mode 100644
index 26abeeee..00000000
--- a/devel-docs/gitlab-ci.md
+++ /dev/null
@@ -1,212 +0,0 @@
-# Gitlab Continuous Integration (CI) for at-spi2-core
-
-Summary: make the robots set up an environment for running the test
-suite, run it, and report back to us.
-
-If you have questions about the CI, mail federico@gnome.org, or [file
-an issue](https://gitlab.gnome.org/GNOME/at-spi2-core/-/issues) and
-mention `@federico` in it.
-
-Table of contents:
-
-[[_TOC_]]
-
-# Quick overview
-
-By having a [`.gitlab-ci.yml`](../.gitlab-ci.yml) file in the toplevel
-directory of a project, Gitlab knows that it must run a continuous
-integration pipeline when certain events occur, for example, when
-someone creates a merge request, or pushes to a branch.
-
-What's a pipeline?  It is an automated version of the following.
-Running the test suite for at-spi2-core involves some repetitive
-steps:
-
-* Create a pristine and minimal environment for testing, without all the random
-  gunk from one's development system.  Gitlab CI uses Linux containers,
-  with pre-built operating system images in the [Open Container
-  Initiative][OCI] format — this is what Docker, Podman, etc. all use.
-
-* Install the build-time dependencies (gcc, meson, libfoo-devel,
-  etc.), the test-time dependencies (dbus-daemon, etc.) in that
-  pristine environment, as well as special tools (lcov, libasan,
-  clang-tools).
-
-* Run the build and install it, and run the test suite.
-
-* Run variations of the build and test suite with other tools — for
-  example, using static analysis during compilation, or with address
-  sanitizer (asan), or with a code coverage tool.  Gitlab can collect
-  the analysis results of each of these tools and present them as part
-  of the merge request that is being evaluated.  It also lets
-  developers obtain those useful results without dealing with a lot of
-  fiddly tools on their own computers.
-  
-Additionally, on each pipeline run we'd like to do extra repetitive
-work like building the reference documentation, and publishing it on a
-web page.
-
-The `.gitlab-ci.yml` file defines the CI pipeline, the jobs it will
-run (build/test, coverage, asan, static-scan, etc.), and the locations
-where each job's artifacts will be stored.
-
-What's an artifact or a job?  Read on!
-
-# A little glossary
-
-**Pipeline** - A collection of **jobs**, which can be run in parallel
-or sequentially.  For example, a pair of "build" and "test" jobs would
-need to run sequentially, but maybe a "render documentation" job can
-run in parallel with them.  Similarly, "build" jobs for various
-distributions or configurations could be run in parallel.
-
-**Job** - Think of it as running a shell script within a container.
-It can have input from other previous jobs: if you have separate
-"build" and "test" jobs, then the "build" job will want to keep around
-its compiled artifacts so that the "test" job can use them.  It can
-provide output artifacts that can be stored for human perusal, or for
-use by other jobs.
-
-**Artifact** - Something produced from a job.  If your job compiles
-binaries, those binaries could be artifacts if you decide to keep them
-around for use later.  A documentation job can produce HTML artifacts
-from the rendered documentation.  A code coverage job will produce a
-coverage report artifact.
-
-**Runner** - An operating system setup for running jobs.
-Gitlab.gnome.org provides runners for Linux, BSD, Windows, and MacOS.
-For example. the Linux runners let you use any OCI image, so you can
-test on openSUSE, Fedora, a custom distro, etc.  You don't normally
-need to be concerned with runners; Gitlab assigns the shared runners
-automatically to your pipeline.
-
-**Container** - You can think of it as a chroot with extra isolation,
-or a lightweight virtual machine.  Basically, the Linux kernel can
-isolate groups of processes in control groups (cgroups).  Each cgroup
-can have a different view of the file system, as if you had a
-different chroot for each cgroup.  Cgroups can be isolated to be in
-their own PID namespace, so running "ps" in the container will not
-show all the processes in the system, but only those inside the
-container's cgroup.  File system overlays allow you to have read-only
-images for the operating system (the OCI images we talked about above)
-plus a read-write overlay that is kept around only during the lifetime
-of a container, or persistently if one wants.  For Gitlab CI one does
-not need to deal with containers directly, but keep in mind that your
-jobs will run inside a container, which is more limited than e.g. a
-shell session on a graphical, development machine.
-
-# The CI pipeline for at-spi2-core
-
-The `.gitlab-ci.yml` file is a more-or-less declarative description
-the CI pipeline, with some `script` sections which are imperative
-commands to actually *do stuff*.
-
-Jobs are run in `stages`, and the names of the stages are declared
-near the beginning of the YAML file.  The stage names are arbitrary;
-the ones here follow some informal GNOME conventions.
-
-Jobs are declared at the toplevel of the YAML file, and they are
-distinguished from other declarations by having a container `image`
-declared for them, as well as a `script` to execute.
-
-Many jobs need exactly the same kind of setup (same container images,
-mostly same package dependencies), so they use `extends:` to use a
-declared template with all that stuff instead of redeclaring it each
-time.
-
-The `build` stage has these jobs:
-
-* `opensuse-x86_64` - Extends the `.only-default` rule,
-  builds/installs the code, and runs the tests.  Generally this is the
-  job that one cares about during regular development.
-  
-* `fedora-x86_64` - Same as the previous job, but runs on Fedora
-  instead of openSUSE.  The intention is to run the build
-  configuration for `dbus-broker` here instead of `dbus-daemon`.
-
-The `analysis` stage has these jobs:
-
-* `static-scan` - Runs static analysis during compilation, which
-  performs interprocedural analysis to detect things like double
-  `free()` or uninitialized struct fields across functions.
-  
-* `asan-build` - Builds and runs with Address Sanitizer (libasan).
-
-* `coverage` - Instruments the build to get code coverage information,
-  and runs the test suite to see how much of the code it manages to
-  exercise.  This is to see which code paths may be untested
-  automatically, and to decide which ones would require manual
-  testing, or refactoring to allow automated testing.
-
-As of 2022/Apr/19 there are some commented-out jobs to generate
-documentation and publish it; this needs to be made to work.
-
-# CI templates
-
-The task of setting up CI for a particular distro or build
-configuration is rather repetitive.  One has to start with a "bare"
-distro image, then install the build-time dependencies that your
-project requires, then that is slow, then you want to build a
-container image instead of installing packages every time, then you
-want to test another distro, then you want to make those container
-images easily available to your project's forks, and then you start
-pulling your hair.
-
-[Fredesktop CI Templates][ci-templates]
-([documentation][ci-templates-docs]) are a solution to this.  They can
-automatically build container images for various distros, make them
-available to forks of your project, and have some nice amenities to
-reduce the maintenance burden.
-
-At-spi2-core uses CI templates to test its various build
-configurations, since it actually works differently depending on a
-distro's choice of `dbus-daemon` versus `dbus-broker`.
-
-The prebuilt container images are stored here:
-https://gitlab.gnome.org/GNOME/at-spi2-core/container_registry
-
-They get updated automatically thanks to the CI Templates machinery.
-
-# General advice and future work
-
-A failed run of a CI pipeline should trouble you; it either means that
-some test broke, or that something is not completely deterministic.
-Fix it at once.
-
-Try not to accept merge requests that fail the CI, as this will make
-`git bisect` hard in the future.  There are tools like Marge-bot to
-enforce this; ask federico@gnome.org about it.  Read ["The Not Rocket
-Science Rule Of Software
-Engineering"](https://graydon.livejournal.com/186550.html), which can
-be summarized as "automatically maintain a repository of code that
-always passes all the tests" for inspiration.  Marge-bot is an
-implementation of that, and can be used with Gitlab.
-
-If your software can be configured to build with substantial changes,
-the CI pipeline should have jobs that test each of those
-configurations.  For example, at-spi-bus-launcher operates differently
-depending on whether `dbus-daemon` or `dbus-broker` are being used.  As of
-2022/Apr/19 the CI only tests `dbus-daemon`; there should be a test for
-dbus-broker, too, in the `fedora-x86_64` job since that is one of the
-distros that uses `dbus-broker`.
-
-Although the YAML syntax for `.gitlab-ci.yml` is a bit magic, the
-scripts and configuration are quite amenable to refactoring.  Do it
-often!
-
-Minimizing the amount of time that CI takes to run is a good goal.  It
-reduces energy consumption in the build farm, and allows you to have a
-faster feedback loop.  Instead of installing package dependencies on
-each job, we can move to prebuilt container images.
-
-# References
-
-Full documentation for Gitlab CI: https://docs.gitlab.com/ee/ci/
-
-Introduction to Gitlab CI: https://docs.gitlab.com/ee/ci/quick_start/index.html
-
-Freedesktop CI templates: https://gitlab.freedesktop.org/freedesktop/ci-templates/
-
-[OCI]: https://opencontainers.org/
-[ci-templates]: https://gitlab.freedesktop.org/freedesktop/ci-templates/
-[ci-templates-docs]: https://freedesktop.pages.freedesktop.org/ci-templates/
diff --git a/devel-docs/gitlab-ci.rst b/devel-docs/gitlab-ci.rst
new file mode 100644
index 00000000..27df04be
--- /dev/null
+++ b/devel-docs/gitlab-ci.rst
@@ -0,0 +1,216 @@
+Gitlab Continuous Integration (CI) for at-spi2-core
+===================================================
+
+Summary: make the robots set up an environment for running the test
+suite, run it, and report back to us.
+
+If you have questions about the CI, mail federico@gnome.org, or `file an
+issue <https://gitlab.gnome.org/GNOME/at-spi2-core/-/issues>`__ and
+mention ``@federico`` in it.
+
+Table of contents:
+
+[[*TOC*]]
+
+Quick overview
+==============
+
+By having a ```.gitlab-ci.yml`` <../.gitlab-ci.yml>`__ file in the
+toplevel directory of a project, Gitlab knows that it must run a
+continuous integration pipeline when certain events occur, for example,
+when someone creates a merge request, or pushes to a branch.
+
+What’s a pipeline? It is an automated version of the following. Running
+the test suite for at-spi2-core involves some repetitive steps:
+
+-  Create a pristine and minimal environment for testing, without all
+   the random gunk from one’s development system. Gitlab CI uses Linux
+   containers, with pre-built operating system images in the `Open
+   Container Initiative <https://opencontainers.org/>`__ format — this
+   is what Docker, Podman, etc. all use.
+
+-  Install the build-time dependencies (gcc, meson, libfoo-devel, etc.),
+   the test-time dependencies (dbus-daemon, etc.) in that pristine
+   environment, as well as special tools (lcov, libasan, clang-tools).
+
+-  Run the build and install it, and run the test suite.
+
+-  Run variations of the build and test suite with other tools — for
+   example, using static analysis during compilation, or with address
+   sanitizer (asan), or with a code coverage tool. Gitlab can collect
+   the analysis results of each of these tools and present them as part
+   of the merge request that is being evaluated. It also lets developers
+   obtain those useful results without dealing with a lot of fiddly
+   tools on their own computers.
+
+Additionally, on each pipeline run we’d like to do extra repetitive work
+like building the reference documentation, and publishing it on a web
+page.
+
+The ``.gitlab-ci.yml`` file defines the CI pipeline, the jobs it will
+run (build/test, coverage, asan, static-scan, etc.), and the locations
+where each job’s artifacts will be stored.
+
+What’s an artifact or a job? Read on!
+
+A little glossary
+=================
+
+**Pipeline** - A collection of **jobs**, which can be run in parallel or
+sequentially. For example, a pair of “build” and “test” jobs would need
+to run sequentially, but maybe a “render documentation” job can run in
+parallel with them. Similarly, “build” jobs for various distributions or
+configurations could be run in parallel.
+
+**Job** - Think of it as running a shell script within a container. It
+can have input from other previous jobs: if you have separate “build”
+and “test” jobs, then the “build” job will want to keep around its
+compiled artifacts so that the “test” job can use them. It can provide
+output artifacts that can be stored for human perusal, or for use by
+other jobs.
+
+**Artifact** - Something produced from a job. If your job compiles
+binaries, those binaries could be artifacts if you decide to keep them
+around for use later. A documentation job can produce HTML artifacts
+from the rendered documentation. A code coverage job will produce a
+coverage report artifact.
+
+**Runner** - An operating system setup for running jobs.
+Gitlab.gnome.org provides runners for Linux, BSD, Windows, and MacOS.
+For example. the Linux runners let you use any OCI image, so you can
+test on openSUSE, Fedora, a custom distro, etc. You don’t normally need
+to be concerned with runners; Gitlab assigns the shared runners
+automatically to your pipeline.
+
+**Container** - You can think of it as a chroot with extra isolation, or
+a lightweight virtual machine. Basically, the Linux kernel can isolate
+groups of processes in control groups (cgroups). Each cgroup can have a
+different view of the file system, as if you had a different chroot for
+each cgroup. Cgroups can be isolated to be in their own PID namespace,
+so running “ps” in the container will not show all the processes in the
+system, but only those inside the container’s cgroup. File system
+overlays allow you to have read-only images for the operating system
+(the OCI images we talked about above) plus a read-write overlay that is
+kept around only during the lifetime of a container, or persistently if
+one wants. For Gitlab CI one does not need to deal with containers
+directly, but keep in mind that your jobs will run inside a container,
+which is more limited than e.g. a shell session on a graphical,
+development machine.
+
+The CI pipeline for at-spi2-core
+================================
+
+The ``.gitlab-ci.yml`` file is a more-or-less declarative description
+the CI pipeline, with some ``script`` sections which are imperative
+commands to actually *do stuff*.
+
+Jobs are run in ``stages``, and the names of the stages are declared
+near the beginning of the YAML file. The stage names are arbitrary; the
+ones here follow some informal GNOME conventions.
+
+Jobs are declared at the toplevel of the YAML file, and they are
+distinguished from other declarations by having a container ``image``
+declared for them, as well as a ``script`` to execute.
+
+Many jobs need exactly the same kind of setup (same container images,
+mostly same package dependencies), so they use ``extends:`` to use a
+declared template with all that stuff instead of redeclaring it each
+time.
+
+The ``build`` stage has these jobs:
+
+-  ``opensuse-x86_64`` - Extends the ``.only-default`` rule,
+   builds/installs the code, and runs the tests. Generally this is the
+   job that one cares about during regular development.
+
+-  ``fedora-x86_64`` - Same as the previous job, but runs on Fedora
+   instead of openSUSE. The intention is to run the build configuration
+   for ``dbus-broker`` here instead of ``dbus-daemon``.
+
+The ``analysis`` stage has these jobs:
+
+-  ``static-scan`` - Runs static analysis during compilation, which
+   performs interprocedural analysis to detect things like double
+   ``free()`` or uninitialized struct fields across functions.
+
+-  ``asan-build`` - Builds and runs with Address Sanitizer (libasan).
+
+-  ``coverage`` - Instruments the build to get code coverage
+   information, and runs the test suite to see how much of the code it
+   manages to exercise. This is to see which code paths may be untested
+   automatically, and to decide which ones would require manual testing,
+   or refactoring to allow automated testing.
+
+As of 2022/Apr/19 there are some commented-out jobs to generate
+documentation and publish it; this needs to be made to work.
+
+CI templates
+============
+
+The task of setting up CI for a particular distro or build configuration
+is rather repetitive. One has to start with a “bare” distro image, then
+install the build-time dependencies that your project requires, then
+that is slow, then you want to build a container image instead of
+installing packages every time, then you want to test another distro,
+then you want to make those container images easily available to your
+project’s forks, and then you start pulling your hair.
+
+`Fredesktop CI
+Templates <https://gitlab.freedesktop.org/freedesktop/ci-templates/>`__
+(`documentation <https://freedesktop.pages.freedesktop.org/ci-templates/>`__)
+are a solution to this. They can automatically build container images
+for various distros, make them available to forks of your project, and
+have some nice amenities to reduce the maintenance burden.
+
+At-spi2-core uses CI templates to test its various build configurations,
+since it actually works differently depending on a distro’s choice of
+``dbus-daemon`` versus ``dbus-broker``.
+
+The prebuilt container images are stored here:
+https://gitlab.gnome.org/GNOME/at-spi2-core/container_registry
+
+They get updated automatically thanks to the CI Templates machinery.
+
+General advice and future work
+==============================
+
+A failed run of a CI pipeline should trouble you; it either means that
+some test broke, or that something is not completely deterministic. Fix
+it at once.
+
+Try not to accept merge requests that fail the CI, as this will make
+``git bisect`` hard in the future. There are tools like Marge-bot to
+enforce this; ask federico@gnome.org about it. Read `“The Not Rocket
+Science Rule Of Software
+Engineering” <https://graydon.livejournal.com/186550.html>`__, which can
+be summarized as “automatically maintain a repository of code that
+always passes all the tests” for inspiration. Marge-bot is an
+implementation of that, and can be used with Gitlab.
+
+If your software can be configured to build with substantial changes,
+the CI pipeline should have jobs that test each of those configurations.
+For example, at-spi-bus-launcher operates differently depending on
+whether ``dbus-daemon`` or ``dbus-broker`` are being used. As of
+2022/Apr/19 the CI only tests ``dbus-daemon``; there should be a test
+for dbus-broker, too, in the ``fedora-x86_64`` job since that is one of
+the distros that uses ``dbus-broker``.
+
+Although the YAML syntax for ``.gitlab-ci.yml`` is a bit magic, the
+scripts and configuration are quite amenable to refactoring. Do it
+often!
+
+Minimizing the amount of time that CI takes to run is a good goal. It
+reduces energy consumption in the build farm, and allows you to have a
+faster feedback loop. Instead of installing package dependencies on each
+job, we can move to prebuilt container images.
+
+References
+==========
+
+Full documentation for Gitlab CI: https://docs.gitlab.com/ee/ci/
+
+Introduction to Gitlab CI:
+https://docs.gitlab.com/ee/ci/quick_start/index.html
+
+Freedesktop CI templates:
+https://gitlab.freedesktop.org/freedesktop/ci-templates/
diff --git a/devel-docs/roadmap.md b/devel-docs/roadmap.md
deleted file mode 100644
index c88535d1..00000000
--- a/devel-docs/roadmap.md
+++ /dev/null
@@ -1,177 +0,0 @@
-# Accessibility infrastructure roadmap
-
-Note that this roadmap refers exclusively to **cleanups** and **paying
-technical debt**.  It does not yet refer to actually changing the
-accessibility interfaces, or the way accessibility works in general.
-
-## High level goals, detailed below
-
-* Make at-spi2-core/xml the authoritative version of the a11y interfaces.
-
-* Remove all the hand-written DBus code in at-spi2-core; replace with
-  gdbus as generated from the XML files.
-
-* Add good end-to-end tests, to complement the ones already in at-spi2-atk.
-
-* Remove as much duplication / leftovers from the CORBA days /
-  compatibility hacks as we can.
-
-* Give people the confidence that the accessibility stack works, so
-  it's their responsibility to make their apps and gnome-shell
-  accessible.
-
-## Short term tasks
-
-* Merge these repositories into a single one: at-spi2-core, atk,
-  at-spi2-atk.  They are tightly coupled, and it will be much easier
-  to test/refactor them if the code is in the same repo.  See "[merge
-  the repositories](#merge-the-repositories)" below for details.
-  
-* Replace manually-written DBus code in at-spi2-core for automatically
-  generated code.  See "[DBus update for
-  libatspi](#dbus-update-for-libatspi)" below for details.
-  
-* [Make the XML interfaces the single source of truth](#make-the-xml-interfaces-the-single-source-of-truth).
-
-# Details on big tasks
-  
-## Merge the repositories
-
-Merging at-spi2-core, atk, and at-spi2-atk into a single repository
-will make end-to-end testing easier.  As of 2022/May/27, at-spi2-atk
-has a few end-to-end tests, which do not manage to exercise all the
-code in libatspi or in atk.  Having all the code in the same
-repository will make it easier to refactor and test things.  Some
-reasons to merge:
-
-* at-spi2-atk has the real end-to-end integration tests for
-  at-spi2-core; it tests the part for an accessible application and
-  the accessibility technology together, with the registry daemon in
-  the middle.  It would be nice to run these tests automatically when
-  any of at-spi2-core or atk changes.
-  
-* Both at-spi2-atk and pyatspi2 have "dummy" implementations of the
-  ATK interfaces to use with their tests.  It may be possible to
-  deduplicate that.
-
-* Doing refactoring across all modules will be easier if their tests
-  are in a single place.
-  
-* We only have to get the CI working once, instead of three times.
-
-Some cool things in at-spi2-core's CI that now work for all the
-accessibility middleware:
-
-* CI pipelines run the test suite and generate a code coverage report.
-  This can be used to fine-tune tests, or decide how to refactor
-  things for finer-grained testing.
-
-* Static analysis.  Fix broken C code as early as possible.
-
-* Address Sanitizer - runtime analysis; does not fully work yet, but
-  the basics are there.
-
-* Infrastructure to test build configurations for various distro
-  images, e.g. dbus-daemon for openSUSE, versus dbus-broker for
-  Fedora - those have different code paths.
-
-## Make the XML interfaces the single source of truth
-
-In the past the at-spi2-core/xml files, which define the DBus
-interfaces for accessibility, have gotten out of sync with
-at-spi2-core's own C code, because it does DBus calls by hand instead
-of using an autogenerated binding - there weren't any at the time it
-was written.  Also they have gotten out of sync with external copies,
-like GTK.  Perhaps we can add some bits to GTK's CI scripts to
-guarantee that this doesn't happen, or make GTK just reference
-at-spi2-core/xml directly.
-
-It may not be possible to "disappear" libatspi2 and rely only on an
-autogenerated binding for the XML DBus interfaces everywhere, but that
-should certainly be a goal.
-
-## Remove hand-written DBus code
-
-My initial goal is to replace it with gdbus from GIO (an auto-generated C binding to XML
-interfaces).  I want to experiment with a few strategies to make this easier.  Right now
-all the DBus code is interwoven with logic from at-spi2-core, so the first thing is to
-separate them.  Then, replace the DBus code in one shot for gdbus.
-
-For example, there's quite a bit of code like this:
-
-```c
-static void
-handle_some_method (DBusMessage *message)
-{
-  foo = demarshal_a_bit ();
-  bar = find_the_accessible ();
-  bar_set_foo (bar, foo);
-
-  baz = demarshal_a_bit ();
-  bar_set_baz (bar, baz);
-
-  while (some_logic_here)
-  {
-    qux = demarshal_something ();
-    blah_blah (qux, bar);
-  }
-
-  /* etc */
-}
-```
-
-So I would first split it into a part that demarshals everything, and then one that does the logic:
-
-```c
-typedef struct {
-  Accessible accessible;
-  Foo foo;
-  Baz baz;
-  Qux quxes[];
-} SomeMethodArgs;
-
-handle_some_method (DBusMessage *message)
-{
-  SomeMethodArgs args;
-
-  if (demarshal_some_method_args (message, &args) != SUCCESS)
-  {
-    return ERROR;
-  }
-
-  do_the_thing (args.accessible, args.foo, args.baz, args.quxes);
-}
-```
-
-Once everything is split apart, it's a lot easier to replace the demarshalers with gdbus
-calls, and the rest of the logic can hopefully remain unchanged.
-
-As a side benefit, this may allow testing the logic without having to worry about
-inter-process communication.  Test the thing; assume communication works.
-
-It may not be possible to separate all such cases so cleanly.
-However, if a certain "sequence" requires intermediate IPC, then that
-is a good indication for a less granular interface to add later:
-instead of querying for an object and then for each of its properties
-/ children / etc., maybe send the whole object's tree in a single
-call.
-
-(Future goal: this separation of IPC vs. logic may make it easier, to
-port the accessibility middleware to Rust - something I'd really like
-to do.)
-
-## End-to-end tests
-
-There are already some end-to-end tests in at-spi2-atk/tests.  They
-create a mock AT and a mock accessible application, and ensure that
-what they communicate through the accessibility bus matches on both
-ends.
-
-These tests are good!  Let's add more extensive ones to help test
-things like event throttling, unstable applications, compatibility
-APIs, etc.
-
-## Should we merge pyatspi2 in here?
-
-Maybe!  It is a compatibility layer, through and through, and maybe we
-can disappear it gradually if we change Orca in lockstep.
diff --git a/devel-docs/roadmap.rst b/devel-docs/roadmap.rst
new file mode 100644
index 00000000..3f194f14
--- /dev/null
+++ b/devel-docs/roadmap.rst
@@ -0,0 +1,188 @@
+Accessibility infrastructure roadmap
+====================================
+
+Note that this roadmap refers exclusively to **cleanups** and **paying
+technical debt**. It does not yet refer to actually changing the
+accessibility interfaces, or the way accessibility works in general.
+
+High level goals, detailed below
+--------------------------------
+
+-  Make at-spi2-core/xml the authoritative version of the a11y
+   interfaces.
+
+-  Remove all the hand-written DBus code in at-spi2-core; replace with
+   gdbus as generated from the XML files.
+
+-  Add good end-to-end tests, to complement the ones already in
+   at-spi2-atk.
+
+-  Remove as much duplication / leftovers from the CORBA days /
+   compatibility hacks as we can.
+
+-  Give people the confidence that the accessibility stack works, so
+   it’s their responsibility to make their apps and gnome-shell
+   accessible.
+
+Short term tasks
+----------------
+
+-  Merge these repositories into a single one: at-spi2-core, atk,
+   at-spi2-atk. They are tightly coupled, and it will be much easier to
+   test/refactor them if the code is in the same repo. See “`merge the
+   repositories <#merge-the-repositories>`__” below for details.
+
+-  Replace manually-written DBus code in at-spi2-core for automatically
+   generated code. See “`DBus update for
+   libatspi <#dbus-update-for-libatspi>`__” below for details.
+
+-  `Make the XML interfaces the single source of
+   truth <#make-the-xml-interfaces-the-single-source-of-truth>`__.
+
+Details on big tasks
+====================
+
+Merge the repositories
+----------------------
+
+Merging at-spi2-core, atk, and at-spi2-atk into a single repository will
+make end-to-end testing easier. As of 2022/May/27, at-spi2-atk has a few
+end-to-end tests, which do not manage to exercise all the code in
+libatspi or in atk. Having all the code in the same repository will make
+it easier to refactor and test things. Some reasons to merge:
+
+-  at-spi2-atk has the real end-to-end integration tests for
+   at-spi2-core; it tests the part for an accessible application and the
+   accessibility technology together, with the registry daemon in the
+   middle. It would be nice to run these tests automatically when any of
+   at-spi2-core or atk changes.
+
+-  Both at-spi2-atk and pyatspi2 have “dummy” implementations of the ATK
+   interfaces to use with their tests. It may be possible to deduplicate
+   that.
+
+-  Doing refactoring across all modules will be easier if their tests
+   are in a single place.
+
+-  We only have to get the CI working once, instead of three times.
+
+Some cool things in at-spi2-core’s CI that now work for all the
+accessibility middleware:
+
+-  CI pipelines run the test suite and generate a code coverage report.
+   This can be used to fine-tune tests, or decide how to refactor things
+   for finer-grained testing.
+
+-  Static analysis. Fix broken C code as early as possible.
+
+-  Address Sanitizer - runtime analysis; does not fully work yet, but
+   the basics are there.
+
+-  Infrastructure to test build configurations for various distro
+   images, e.g. dbus-daemon for openSUSE, versus dbus-broker for Fedora
+   - those have different code paths.
+
+Make the XML interfaces the single source of truth
+--------------------------------------------------
+
+In the past the at-spi2-core/xml files, which define the DBus interfaces
+for accessibility, have gotten out of sync with at-spi2-core’s own C
+code, because it does DBus calls by hand instead of using an
+autogenerated binding - there weren’t any at the time it was written.
+Also they have gotten out of sync with external copies, like GTK.
+Perhaps we can add some bits to GTK’s CI scripts to guarantee that this
+doesn’t happen, or make GTK just reference at-spi2-core/xml directly.
+
+It may not be possible to “disappear” libatspi2 and rely only on an
+autogenerated binding for the XML DBus interfaces everywhere, but that
+should certainly be a goal.
+
+Remove hand-written DBus code
+-----------------------------
+
+My initial goal is to replace it with gdbus from GIO (an auto-generated
+C binding to XML interfaces). I want to experiment with a few strategies
+to make this easier. Right now all the DBus code is interwoven with
+logic from at-spi2-core, so the first thing is to separate them. Then,
+replace the DBus code in one shot for gdbus.
+
+For example, there’s quite a bit of code like this:
+
+.. code:: c
+
+   static void
+   handle_some_method (DBusMessage *message)
+   {
+     foo = demarshal_a_bit ();
+     bar = find_the_accessible ();
+     bar_set_foo (bar, foo);
+
+     baz = demarshal_a_bit ();
+     bar_set_baz (bar, baz);
+
+     while (some_logic_here)
+     {
+       qux = demarshal_something ();
+       blah_blah (qux, bar);
+     }
+
+     /* etc */
+   }
+
+So I would first split it into a part that demarshals everything, and
+then one that does the logic:
+
+.. code:: c
+
+   typedef struct {
+     Accessible accessible;
+     Foo foo;
+     Baz baz;
+     Qux quxes[];
+   } SomeMethodArgs;
+
+   handle_some_method (DBusMessage *message)
+   {
+     SomeMethodArgs args;
+
+     if (demarshal_some_method_args (message, &args) != SUCCESS)
+     {
+       return ERROR;
+     }
+
+     do_the_thing (args.accessible, args.foo, args.baz, args.quxes);
+   }
+
+Once everything is split apart, it’s a lot easier to replace the
+demarshalers with gdbus calls, and the rest of the logic can hopefully
+remain unchanged.
+
+As a side benefit, this may allow testing the logic without having to
+worry about inter-process communication. Test the thing; assume
+communication works.
+
+It may not be possible to separate all such cases so cleanly. However,
+if a certain “sequence” requires intermediate IPC, then that is a good
+indication for a less granular interface to add later: instead of
+querying for an object and then for each of its properties / children /
+etc., maybe send the whole object’s tree in a single call.
+
+(Future goal: this separation of IPC vs. logic may make it easier, to
+port the accessibility middleware to Rust - something I’d really like to
+do.)
+
+End-to-end tests
+----------------
+
+There are already some end-to-end tests in at-spi2-atk/tests. They
+create a mock AT and a mock accessible application, and ensure that what
+they communicate through the accessibility bus matches on both ends.
+
+These tests are good! Let’s add more extensive ones to help test things
+like event throttling, unstable applications, compatibility APIs, etc.
+
+Should we merge pyatspi2 in here?
+---------------------------------
+
+Maybe! It is a compatibility layer, through and through, and maybe we
+can disappear it gradually if we change Orca in lockstep.
diff --git a/devel-docs/toolkits.md b/devel-docs/toolkits.md
deleted file mode 100644
index c05318a8..00000000
--- a/devel-docs/toolkits.md
+++ /dev/null
@@ -1,52 +0,0 @@
-# Accessibility implementations in different toolkits
-
-## Toolkits that use the DBus APIs directly
-
-### GTK4
-
-Sources: [`gtk4/gtk/a11y`](https://gitlab.gnome.org/GNOME/gtk/-/tree/main/gtk/a11y)
-
-## Qt5
-
-Sources: [`qtbase/src/gui/accessible/linux`](https://github.com/qt/qtbase/tree/dev/src/gui/accessible/linux)
-
-Note: Qt's implementation of
-[Cache.GetItems](https://github.com/qt/qtbase/blob/dev/src/gui/accessible/linux/qspi_struct_marshallers.cpp#L41-L71)
-uses the old signature `a((so)(so)(so)a(so)assusau)` instead of the
-preferred/new `a((so)(so)(so)iiassusau)`.
-
-## WebKit
-
-Sources: [`WebKit/Source/WebCore/accessibility/atspi`](https://github.com/WebKit/WebKit/tree/main/Source/WebCore/accessibility/atspi)
-
-
-## Toolkits that use ATK
-
-## GTK3
-
-Sources: [`gtk3/gtk/a11y`](https://gitlab.gnome.org/GNOME/gtk/-/tree/gtk-3-24/gtk/a11y)
-
-## gnome-shell / St / via clutter's cally
-
-Sources: [`mutter/clutter/clutter/cally`](https://gitlab.gnome.org/GNOME/mutter/-/tree/main/clutter/clutter/cally)
-
-## Mozilla Firefox
-
-Sources: [`gecko-dev/accessible/atk`](https://github.com/mozilla/gecko-dev/tree/master/accessible/atk)
-
-## Chromium
-
-Uses both ATK and libatspi?
-
-Sources:
-* [`chromium/ui/accessibility/platform/*auralinux*`](https://github.com/chromium/chromium/tree/main/ui/accessibility/platform) (atk)
-* [`chromium/ui/accessibility/platform/inspect/*auralinux*`](https://github.com/chromium/chromium/tree/main/ui/accessibility/platform/inspect) (atspi)
-* [`chromium/content/browser/accessibility/*auralinux*`](https://github.com/chromium/chromium/tree/main/content/browser/accessibility/) (atspi and atk)
-
-## LibreOffice
-
-Sources: [`LibreOffice/core/vcl/unx/gtk3/a11y`](https://github.com/LibreOffice/core/tree/master/vcl/unx/gtk3/a11y)
-
-## Java Swing - via java-atk-wrapper
-
-Sources: [`java-atk-wrapper`](https://gitlab.gnome.org/GNOME/java-atk-wrapper)
diff --git a/devel-docs/toolkits.rst b/devel-docs/toolkits.rst
new file mode 100644
index 00000000..609cb911
--- /dev/null
+++ b/devel-docs/toolkits.rst
@@ -0,0 +1,74 @@
+Accessibility implementations in different toolkits
+===================================================
+
+Toolkits that use the DBus APIs directly
+----------------------------------------
+
+GTK4
+~~~~
+
+Sources:
+```gtk4/gtk/a11y`` <https://gitlab.gnome.org/GNOME/gtk/-/tree/main/gtk/a11y>`__
+
+Qt5
+---
+
+Sources:
+```qtbase/src/gui/accessible/linux`` <https://github.com/qt/qtbase/tree/dev/src/gui/accessible/linux>`__
+
+Note: Qt’s implementation of
+`Cache.GetItems <https://github.com/qt/qtbase/blob/dev/src/gui/accessible/linux/qspi_struct_marshallers.cpp#L41-L71>`__
+uses the old signature ``a((so)(so)(so)a(so)assusau)`` instead of the
+preferred/new ``a((so)(so)(so)iiassusau)``.
+
+WebKit
+------
+
+Sources:
+```WebKit/Source/WebCore/accessibility/atspi`` <https://github.com/WebKit/WebKit/tree/main/Source/WebCore/accessibility/atspi>`__
+
+Toolkits that use ATK
+---------------------
+
+GTK3
+----
+
+Sources:
+```gtk3/gtk/a11y`` <https://gitlab.gnome.org/GNOME/gtk/-/tree/gtk-3-24/gtk/a11y>`__
+
+gnome-shell / St / via clutter’s cally
+--------------------------------------
+
+Sources:
+```mutter/clutter/clutter/cally`` <https://gitlab.gnome.org/GNOME/mutter/-/tree/main/clutter/clutter/cally>`__
+
+Mozilla Firefox
+---------------
+
+Sources:
+```gecko-dev/accessible/atk`` <https://github.com/mozilla/gecko-dev/tree/master/accessible/atk>`__
+
+Chromium
+--------
+
+Uses both ATK and libatspi?
+
+Sources: \*
+```chromium/ui/accessibility/platform/*auralinux*`` <https://github.com/chromium/chromium/tree/main/ui/accessibility/platform>`__
+(atk) \*
+```chromium/ui/accessibility/platform/inspect/*auralinux*`` <https://github.com/chromium/chromium/tree/main/ui/accessibility/platform/inspect>`__
+(atspi) \*
+```chromium/content/browser/accessibility/*auralinux*`` <https://github.com/chromium/chromium/tree/main/content/browser/accessibility/>`__
+(atspi and atk)
+
+LibreOffice
+-----------
+
+Sources:
+```LibreOffice/core/vcl/unx/gtk3/a11y`` <https://github.com/LibreOffice/core/tree/master/vcl/unx/gtk3/a11y>`__
+
+Java Swing - via java-atk-wrapper
+---------------------------------
+
+Sources:
+```java-atk-wrapper`` <https://gitlab.gnome.org/GNOME/java-atk-wrapper>`__