Autodoc extensions

Python-sdbus has an extension for Sphinx autodoc that can document dbus interfaces.

To use it include "sdbus.autodoc" extension in your conf.py file.

extensions = ['sdbus.autodoc']

The extension can document interface class bodies. For example, python-sdbus-networkmanager uses it to document the classes.

.. autoclass:: sdbus_async.networkmanager.NetworkManagerDeviceBluetoothInterfaceAsync
    :members:

Warning

Autodoc extension is early in development and has multiple issues. For example, the inheritance :inherited-members: does not work on the dbus elements.

Writing docstrings

The dbus methods should be documented same way as the regular function would. See Sphinx documentation on possible fields

Example docstring for a dbus method:

@dbus_method_async('s', method_name='GetConnectionUnixProcessID')
async def get_connection_pid(self, service_name: str) -> int:
    """Get process ID that owns a specified name.

    :param service_name: Service name to query.
    :return: PID of name owner
    :raises DbusNameHasNoOwnerError: Nobody owns that name
    """
    raise NotImplementedError

Dbus properties and signals will be annotated with type taken from the stub function.

@dbus_property_async('as')
def features(self) -> List[str]:
    """List of dbus daemon features.

    Features include:

    * 'AppArmor' - Messages filtered by AppArmor on this bus.
    * 'HeaderFiltering' - Messages are filtered if they have incorrect \
                          header fields.
    * 'SELinux' - Messages filtered by SELinux on this bus.
    * 'SystemdActivation' - services activated by systemd if their \
                           .service file specifies a dbus name.
    """
    raise NotImplementedError

No parameters are supported at the moment for properties and signals.