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.