Autodoc extensions
Python-sdbus has an extension for Sphinx autodoc that can document D-Bus 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 D-Bus elements.
Writing docstrings
The D-Bus methods should be documented same way as the regular function would. See Sphinx documentation on possible fields
Example docstring for a D-Bus 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
D-Bus properties and signals will be annotated with type taken from the stub function.
@dbus_property_async('as')
def features(self) -> List[str]:
"""List of D-Bus 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 D-Bus name.
"""
raise NotImplementedError
No parameters are supported at the moment for properties and signals.