More documentation improvements

doc/portal-interfaces.rst → doc/api-reference.rst

@@ -1,5 +1,5 @@
-D-Bus Interfaces for App Developers
-===================================
+API Reference
+=============
 
 Portal interfaces are available to sandboxed applications with the default
 filtered session bus access of Flatpak.

doc/backends.rst

@@ -0,0 +1,119 @@
+Portal Backends
+===============
+
+The separation of the portal infrastructure into frontend and backend is a clean
+way to provide suitable user interfaces that fit into different desktop
+environments, while sharing the portal frontend.
+
+The portal backends are focused on providing user interfaces and accessing
+session- or host-specific APIs and resources. Details of interacting with the
+containment infrastructure such as checking access, registering files in the
+document portal, etc., are handled by the portal frontend.
+
+Portal backends can be layered together. For example, in a GNOME session, most
+portal backend interfaces are implemented by the GNOME portal backend, but
+the :doc:`org.freedesktop.impl.portal.Access <doc-org.freedesktop.impl.portal.Access>`
+interface is implemented by GNOME Shell.
+
+Adding a New Backend
+--------------------
+
+For a new portal backend (let's call it ``foo``) to be discoverable by XDG
+Desktop Portal, the following steps are necessary:
+
+* Implement one or more :doc:`backend D-Bus interfaces <impl-dbus-interfaces>`
+  in an executable. This executable must be `D-Bus activatable
+  <https://specifications.freedesktop.org/desktop-entry-spec/1.1/ar01s07.html>`_.
+* Install ``foo.portal`` file under `{DATADIR}/xdg-desktop-portal/portals`.
+  Usually, ``{DATADIR}`` is `/usr/share`. The syntax of the portal file is
+  documented below.
+* Make sure the new backend is picked by XDG Desktop Portal by adding a config
+  file that points to the new ``foo`` portal backend. The syntax of the config
+  file is documented below.
+
+Portal (`.portal`) File
+-----------------------
+
+Portal files are files that allow XDG Desktop Portal to know which portal
+backends are available, and which backend D-Bus interfaces they implement.
+They usually look like this:
+
+.. code-block::
+
+   [portal]
+   DBusName=org.freedesktop.impl.portal.desktop.foo
+   Interfaces=org.freedesktop.impl.portal.AppChooser;org.freedesktop.impl.portal.Background;org.freedesktop.impl.portal.Clipboard;org.freedesktop.impl.portal.FileChooser;org.freedesktop.impl.portal.Lockdown;org.freedesktop.impl.portal.RemoteDesktop;org.freedesktop.impl.portal.ScreenCast;
+   UseIn=gnome
+
+The following keys are supported in this file:
+
+* ``DBusName``: the D-Bus activation name of the portal backend service.
+* ``Interfaces``: which :doc:`backend D-Bus interfaces <impl-dbus-interfaces>`
+  this portal backend implements.
+* ``UseIn``: which desktop environments the portal backend should run. This key
+  is officially deprecated, and has been replaced by the config file (see below),
+  but it's recommended to keep it there for legacy systems.
+
+Configuration File
+------------------
+
+Desktop systems may have multiple desktop environments and portal backends
+installed in parallel, and automatically picking portal backends in this situation
+has proven to be a challenge.
+
+For this reason, XDG Desktop Portal uses a config-based matching system. Usually,
+the configuration files are provided by the desktop environments themselves, so
+that e.g. the GNOME-specific portal backends are picked in GNOME sessions. No
+end user intervention is necessary in this case.
+
+Here's an example of a config file distributed by GNOME:
+
+.. code-block::
+
+   [preferred]
+   default=gnome;gtk;
+   org.freedesktop.impl.portal.Access=gnome-shell;gtk;
+   org.freedesktop.impl.portal.Secret=gnome-keyring;
+
+This file specifies that, by default, the ``gnome`` and ``gtk`` portal backends
+must be used. However, specifically for :doc:`org.freedesktop.impl.portal.Access
+<doc-org.freedesktop.impl.portal.Access>`, the ``gnome-shell`` and ``gtk``
+portal backends must be used; and for :doc:`org.freedesktop.impl.portal.Secret
+<doc-org.freedesktop.impl.portal.Secret>`, the ``gnome-keyring`` portal
+backend must be used.
+
+You can read more about the config file syntax, install locations, and more, in
+the portals.conf man page:
+
+.. toctree::
+   :maxdepth: 1
+
+   portals.conf
+
+D-Bus Interfaces
+----------------
+
+Portal backends must implement one or more backend D-Bus interfaces. The list of
+D-Bus interfaces can be found below:
+
+.. toctree::
+   :maxdepth: 1
+
+   impl-dbus-interfaces
+
+Background Apps Monitor
+-----------------------
+
+In addition to managing the regular interfaces that sandboxed applications
+use to interfact with the host system, XDG Desktop Portal also monitors
+running applications without an active window - if the portal backend
+provides an implementation of the Background portal.
+
+This API can be used by host system services to provide rich interfaces to
+manage background running applications.
+
+
+.. toctree::
+   :maxdepth: 1
+
+   doc-org.freedesktop.background.Monitor.rst

doc/common-conventions.rst

@@ -1,63 +1,13 @@
 Common Conventions
 ==================
 
-Requests made via portal interfaces generally involve user interaction, and
-dialogs that can stay open for a long time. Therefore portal APIs don't just use
-async method calls (which time out after at most 25 seconds), but instead return
-results via a Response signal on :ref:`Request<org.freedesktop.portal.Request>`
-objects.
+XDG Desktop Portal uses D-Bus in a slightly uncommon way, due to the potentially
+long-running nature of some of its requests. These different usage patterns are
+documented in the pages below:
 
-Portal APIs don't use properties very much. This is partially because we need to
-be careful about the flow of information, and partially because it would be
-unexpected to have a dialog appear when you just set a property. However, every
-portal has at least one version property that specifies the maximum version
-supported by xdg-desktop-portal.
+.. toctree::
+   :maxdepth: 1
 
-Portal requests
----------------
-
-The general flow of the portal API is that the application makes a portal
-request, the portal replies to that method call with a handle (i.e. object path)
-to a Request object that corresponds to the request. The object is exported on
-the bus and stays alive as long as the user interaction lasts. When the user
-interaction is over, the portal sends a Response signal back to the application
-with the results from the interaction, if any.
-
-To avoid a race condition between the caller subscribing to the signal after
-receiving the reply for the method call and the signal getting emitted, a
-convention for Request object paths has been established that allows the caller
-to subscribe to the signal before making the method call.
-
-Sessions
---------
-
-Some portal requests are connected to each other and need to be used in
-sequence. The pattern we use in such cases is a :ref:`Session<org.freedesktop.portal.Session>`
-object. Just like :ref:`Request<org.freedesktop.portal.Request>`\s, sessions are
-represented by an object path, that is returned by the initial CreateSession
-call of the respective portal. Subsequent calls take the object path of the
-session they operate on as an argument.
-
-Sessions can be ended from the application side by calling the Close() method on
-the session. They can also be closed from the service side, in which case the
-::Closed signal is emitted on the Session object to inform the application.
-
-.. _window-identifiers:
-Parent window identifiers
--------------------------
-
-Most portals interact with the user by showing dialogs. These dialogs should
-generally be placed on top of the application window that triggered them. To
-arrange this, the compositor needs to know about the application window. Many
-portal requests expect a "parent_window" string argument for this reason.
-
-Under X11, the "parent_window" argument should have the form ``x11:<XID>``,
-where ``<XID>`` is the XID of the application window in hexadecimal notation.
-
-Under Wayland, it should have the form ``wayland:<HANDLE>``, where ``<HANDLE>``
-is a surface handle obtained with the `xdg_foreign
-<https://github.com/wayland-project/wayland-protocols/blob/master/unstable/xdg-foreign/xdg-foreign-unstable-v2.xml>`_
-protocol.
-
-For other windowing systems, or if you don't have a suitable handle, just pass
-an empty string for "parent_window".
+   requests
+   sessions
+   window-identifiers

doc/contributing.rst

@@ -0,0 +1,90 @@
+Contributing
+============
+
+Before developing features or fixing bugs, please make sure you are have done
+the following:
+
+- Your code is not on the ``main`` branch of your fork.
+- The code has been tested.
+- All commit messages are properly formatted and commits squashed where
+  appropriate.
+- You have included updates to all appropriate documentation.
+
+We use GitHub pull requests to review contributions. Please be kind and patient
+as code reviews can be long and minutious.
+
+
+Development
+-----------
+
+XDG Desktop Portal usually runs as a user session service, initialized on
+demand through D-Bus activation. It usually starts with the session though,
+as many desktop environments try to talk to XDG Desktop Portal on startup.
+XDG Desktop Portal initializes specific backends through D-Bus activation
+as well.
+
+
+Building
+--------
+
+To build XDG Desktop Portal, first make sure you have the build dependencies
+installed through your distribution's package manager. With them installed,
+run:
+
+.. code-block:: shell
+
+   meson setup . _build
+   meson compile -C _build
+
+Some distributions install portal configuration files in ``/usr``, while Meson
+defaults to the prefix ``/usr/local``. If the portal configuration files in your
+distribution are in ``/usr/share/xdg-desktop-portal/portals``, re-configure
+Meson using ``meson setup --reconfigure . _build --prefix /usr`` and compile
+again.
+
+
+Running
+-------
+
+XDG Desktop Portal needs to own the D-Bus name and replace the user session
+service that might already be running. To do so, run:
+
+.. code-block:: shell
+
+   _build/src/xdg-desktop-portal --replace
+
+You may need to restart backends after replacing XDG Desktop Portal (please
+replace ``[name]`` with the backend name, e.g. ``gnome`` or ``kde`` or ``wlr``):
+
+.. code-block:: shell
+
+   systemctl --user restart xdg-desktop-portal-[name].service
+
+Testing
+-------
+
+To execute the test suite present in XDG Desktop Portal, make sure you built it
+with ``-Dlibportal=enabled``, and run:
+
+.. code-block:: shell
+
+   meson test -C _build
+
+Documentation
+-------------
+
+These instructions are for Fedora, where you will need these packages:
+
+.. code-block::
+
+   sudo dnf install json-glib-devel fuse3-devel gdk-pixbuf2-devel pipewire-devel python3-sphinx flatpak-devel python3-furo python-sphinxext-opengraph python-sphinx-copybutton
+
+Then you can build the website with:
+
+.. code-block:: shell
+
+   meson setup . _build -Ddocumentation=enabled
+   ninja -C _build
+
+Then just load the build website into a browser of your choice from
+``_build/doc/html/index.html``

doc/implementation-interfaces.rst → doc/impl-dbus-interfaces.rst

@@ -1,19 +1,10 @@
-D-Bus Interfaces for Desktop Developers
-=======================================
+Backend D-Bus Interfaces
+========================
 
 The backend interfaces are used by the portal frontend to carry out portal
 requests. They are provided by a separate process (or processes), and are not
 accessible to sandboxed applications.
 
-The separation of the portal infrastructure into frontend and backend is a clean
-way to provide suitable user interfaces that fit into different desktop
-environments, while sharing the portal frontend.
-
-The portal backends are focused on providing user interfaces and accessing
-session- or host-specific APIs and resources. Details of interacting with the
-containment infrastructure such as checking access, registering files in the
-document portal, etc., are handled by the portal frontend. 
-
 .. toctree::
    :maxdepth: 1
 

doc/index.rst

@@ -14,25 +14,40 @@ XDG Desktop Portal
 XDG Desktop Portal allow `Flatpak apps <http://www.flatpak.org>`_, and other desktop
 containment frameworks, to interact with the system in a secure and well defined way.
 
+This documentation covers everything you need to know to build apps that use portals,
+write portal backends for your desktop environment, configure and distribute portals
+as part of a distribution, as well as basic concepts and common conventions.
+
+The documentation pages target primarily app developers, desktop developers, and
+system distributors and administrators. The contents may also be relevant to those
+who have a general interest in portals.
+
 Content Overview
 ----------------
 
-The following sections contain relevant information for **app and desktop developers**:
+This documentation is made up of the following sections:
 
-* :doc:`Background apps monitoring <background-app-monitor>`: service that provides information about apps running in background to **desktop developers**.
-* :doc:`Common conventions <common-conventions>`: coding patterns and principles common when **app and desktop developers** are working with portal APIs.
-* :doc:`Portal interfaces <portal-interfaces>`: portals that **apps** can use to interact with the host system.
-* :doc:`Portal backend interfaces <implementation-interfaces>`: interfaces that **desktop developers** can implement.
+* :doc:`Introduction <introduction>`: learn about the goals, terminology, and
+  reasons to use portals on your apps.
+* :doc:`Common conventions <common-conventions>`: coding patterns and principles
+  common when **app and desktop developers** are working with portal APIs.
+* :doc:`Application API <application-api>`: portal APIs that **apps** can use to
+  interact with the host system.
+* :doc:`Portal backends <backends>`: interfaces and configuration files that
+  **desktop developers** can implement and install in order to write a portal
+  backend.
+* :doc:`Background apps monitoring <introduction>`: service that provides
+  information about apps running in background to **desktop developers**.
 
 XDG Desktop Portal backends are selected and can be configured by using one or more
 configuration files. :doc:`Read more about them here <portals.conf>`.
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
    :hidden:
 
-   portals.conf
+   introduction
    common-conventions
-   portal-interfaces
-   implementation-interfaces
-   background-app-monitor
+   api-reference
+   backends
+   contributing