update docs

ignis/exceptions.py

@@ -1,29 +1,53 @@
 class WindowNotFoundError(Exception):
     """
     Raised when a window is not found.
+
+    Properties:
+        - **window_name** (``str``, required, read-only): The name of the window.
     """
 
     def __init__(self, window_name: str, *args) -> None:
+        self._window_name = window_name
         super().__init__(f'No such window: "{window_name}"', *args)
 
+    @property
+    def window_name(self) -> str:
+        return self._window_name
+
 
 class WindowAddedError(Exception):
     """
     Raised when a window is already added to the application.
+
+    Properties:
+        - **window_name** (``str``, required, read-only): The name of the window.
     """
 
     def __init__(self, window_name: str, *args) -> None:
+        self._window_name = window_name
         super().__init__(f'Window already added: "{window_name}"', *args)
 
+    @property
+    def window_name(self) -> str:
+        return self._window_name
+
 
 class ServiceNotFoundError(Exception):
     """
     Raised when a service with the given name is not found.
+
+    Properties:
+        - **service_name** (``str``, required, read-only): The name of the service.
     """
 
     def __init__(self, service_name: str, *args: object) -> None:
+        self._service_name = service_name
         super().__init__(f'No such service "{service_name}"', *args)
 
+    @property
+    def service_name(self) -> str:
+        return self._service_name
+
 
 class GvcNotFoundError(Exception):
     """
@@ -64,19 +88,35 @@ def __init__(self, *args: object) -> None:
 class OptionNotFoundError(Exception):
     """
     Raised when an option is not found.
+
+    Properties:
+        - **option_name** (``str``, required, read-only): The name of the option.
     """
 
-    def __init__(self, name: str, *args) -> None:
-        super().__init__(f'No such option: "{name}"', *args)
+    def __init__(self, option_name: str, *args) -> None:
+        self._option_name = option_name
+        super().__init__(f'No such option: "{option_name}"', *args)
+
+    @property
+    def option_name(self) -> str:
+        return self._option_name
 
 
 class OptionExistsError(Exception):
     """
     Raised when an option already exists.
+
+    Properties:
+        - **option_name** (``str``, required, read-only): The name of the option.
     """
 
-    def __init__(self, name: str, *args) -> None:
-        super().__init__(f'Option already exists: "{name}"', *args)
+    def __init__(self, option_name: str, *args) -> None:
+        self._option_name = option_name
+        super().__init__(f'Option already exists: "{option_name}"', *args)
+
+    @property
+    def option_name(self) -> str:
+        return self._option_name
 
 
 class GstNotFoundError(Exception):
@@ -93,23 +133,45 @@ def __init__(self, *args: object) -> None:
 class GstPluginNotFoundError(Exception):
     """
     Raised when a GStreamer plugin is not found.
+
+    Properties:
+        - **plugin_name** (``str``, required, read-only): The name of the plugin.
+        - **plugin_package** (``str``, required, read-only): The package name of the plugin.
     """
 
-    def __init__(self, name: str, plugin_package: str, *args) -> None:
+    def __init__(self, plugin_name: str, plugin_package: str, *args) -> None:
+        self._plugin_name = plugin_name
+        self._plugin_package = plugin_package
         super().__init__(
-            f"{name} GStreamer plugin not found! To use the recorder service, install {plugin_package}",
+            f"{plugin_name} GStreamer plugin not found! To use the recorder service, install {plugin_package}",
             *args,
         )
 
+    @property
+    def plugin_name(self) -> str:
+        return self._plugin_name
+
+    @property
+    def plugin_package(self) -> str:
+        return self._plugin_package
+
 
 class SassCompilationError(Exception):
     """
     Raised when Dart Sass compilation fails.
+
+    Properties:
+        - **stderr** (``str``, required, read-only): The stderr output from Dart Sass.
     """
 
     def __init__(self, stderr: str, *args: object) -> None:
+        self._stderr = stderr
         super().__init__(f"SASS compilation error:\n{stderr}", *args)
 
+    @property
+    def stderr(self) -> str:
+        return self._stderr
+
 
 class DartSassNotFoundError(Exception):
     """
@@ -125,11 +187,19 @@ def __init__(self, *args: object) -> None:
 class MonitorNotFoundError(Exception):
     """
     Raised when a monitor with the given ID is not found.
+
+    Properties:
+        - **monitor_id** (``int``, required, read-only): The ID of the monitor.
     """
 
     def __init__(self, monitor_id: int, *args: object) -> None:
+        self._monitor_id = monitor_id
         super().__init__(f"No such monitor with id: {monitor_id}", *args)
 
+    @property
+    def monitor_id(self) -> int:
+        return self._monitor_id
+
 
 class LayerShellNotSupportedError(Exception):
     """

ignis/services/__init__.py

@@ -4,6 +4,21 @@
 
 
 class ServiceClass:
+    """
+    Universal class to access services.
+
+    .. warning::
+
+        Do not initialize this class!
+        Use the already initialized ``Service`` instance as shown below.
+
+    .. code-block:: python
+
+        from ignis.services import Service
+        service_name = Service.get("service_name")
+
+    """
+
     def __init__(self) -> None:
         # modify this dict to add/remove services
         # SHORT_SERVICE_NAME: SERVICE_CLASS_NAME
@@ -25,6 +40,15 @@ def __init__(self) -> None:
     def get(self, service: str) -> IgnisGObject:
         """
         Get a service by its name.
+
+        Args:
+            service (``str``): A service name. It should be in ``snake_case``.
+
+        Returns:
+            IgnisGObject: The service with given name.
+
+        Raises:
+            ServiceNotFoundError: When service with given ID not found.
         """
         if service in self._services:
             if not hasattr(self, f"_{service}"):

ignis/services/audio.py

@@ -33,6 +33,9 @@ class Stream(IgnisGObject):
         - **is_muted** (``bool``, read-write): Whether the stream is muted.
         - **volume** (``float``, read-write): Volume of the stream.
         - **is_default** (``bool``, read-only): Whether the stream is default. Works only for speakers and microphones.
+
+    Raises:
+        GvcNotFoundError: If Gvc is not found.
     """
 
     __gsignals__ = {

ignis/services/hyprland.py

@@ -22,6 +22,9 @@ class HyprlandService(IgnisGObject):
         - **kb_layout** (``str``, read-only): Currenly active keyboard layout.
         - **active_window** (``dict``, read-only): Currenly focused window.
 
+    Raises:
+        HyprlandIPCNotFoundError: If Hyprland IPC is not found.
+
     **Example usage:**
 
     .. code-block:: python

ignis/services/network.py

@@ -148,6 +148,9 @@ class WifiAccessPoint(IgnisGObject):
         - **icon_name** (``str``, read-only): The current icon name for the access point. Depends on signal strength and current connection status.
         - **requires_password** (``bool``, read-only): Whether the access point requires a password to connect.
         - **is_connected** (``bool``, read-only): Whether the device is currently connected to this access point.
+
+    Raises:
+        NetworkManagerNotFoundError: If Network Manager is not found.
     """
 
     def __init__(self, point: NM.AccessPoint, client: NM.Client, device: NM.DeviceWifi):

ignis/services/options.py

@@ -92,10 +92,10 @@ def create_option(self, name: str, default: Any, exists_ok: bool = False) -> Non
         Args:
             name (``str``): The name of the option.
             default (``Any``): The default value for the option.
-            exists_ok (``bool``, optional): If ``True``, do not raise ``OptionExistsError`` if the option already exists. Defaults to ``False``.
+            exists_ok (``bool``, optional): If ``True``, do not raise ``OptionExistsError`` if the option already exists. Default: ``False``.
 
         Raises:
-            OptionExistsError: Raised if the option already exists and ``exists_ok`` is set to ``False``.
+            OptionExistsError: If the option already exists and ``exists_ok`` is set to ``False``.
         """
 
         option = self.__data.get(name, None)
@@ -114,7 +114,7 @@ def remove_option(self, name: str) -> None:
             name (``str``): The name of the option to be removed.
 
         Raises:
-            OptionNotFoundError: Raised if the option does not exist.
+            OptionNotFoundError: If the option does not exist.
         """
         option = self.__data.get(name, None)
         if option:
@@ -133,7 +133,7 @@ def get_option(self, name: str) -> Any:
             The value of the option.
 
         Raises:
-            OptionNotFoundError: Raised if the option does not exist.
+            OptionNotFoundError: If the option does not exist.
         """
         option = self.__data.get(name, None)
 
@@ -150,7 +150,7 @@ def set_option(self, name: str, value: Any) -> None:
             name (``str``): The name of the option.
             value (``Any``): The value to set for the option.
         Raises:
-            OptionNotFoundError: Raised if the option does not exist.
+            OptionNotFoundError: If the option does not exist.
         """
         option = self.__data.get(name, None)
         if option:
@@ -171,7 +171,7 @@ def bind_option(self, name: str, transform: callable = None) -> Binding:
             ``Binding``.
 
         Raises:
-            OptionNotFoundError: Raised if the option does not exist.
+            OptionNotFoundError: If the option does not exist.
         """
         option = self.__data.get(name, None)
         if not option:
@@ -189,7 +189,7 @@ def connect_option(self, name: str, callback: callable) -> None:
             callback (``callable``): A function to call when the option value changes. The new value of the option will be passed to this function.
 
         Raises:
-            OptionNotFoundError: Raised if the option does not exist.
+            OptionNotFoundError: If the option does not exist.
         """
         option = self.__data.get(name, None)
         if not option:

ignis/services/recorder.py

@@ -103,6 +103,10 @@ class RecorderService(IgnisGObject):
         - **default_file_location** (``str``, read-write, default: ``"$HOME/Videos"``): Default location for saving recordings.
         - **default_filename** (``str``, read-write, default: ``"%Y-%m-%d_%H-%M-%S.mp4"``): Default filename for recordings. Supports time formating.
 
+    Raises:
+        GstNotFoundError: If GStreamer is not found.
+        GstPluginNotFoundError: If GStreamer plugin is not found.
+
     **Example usage:**
 
     .. code-block:: python

ignis/utils/file_monitor.py

@@ -38,10 +38,19 @@ class FileMonitor(IgnisGObject):
     Properties:
         - **path** (``str``, read-only): The path to the file or directory to be monitored.
         - **recursive** (``bool``, optional, read-only): Whether monitoring is recursive (monitor all subdirectories and files).
-        - **flags** (``str``, optional, read-only): What the monitor will watch for. Possible values: ``"none"``, ``"watch_mounts"``, ``"send_moved"``, ``"watch_hard_links"``, ``"watch_moves"``. See `Gio.FileMonitorFlags <https://lazka.github.io/pgi-docs/Gio-2.0/flags.html#Gio.FileMonitorFlags>`_ for more info.
+        - **flags** (``str``, optional, read-only): What the monitor will watch for.
         - **callback** (``callable``, optional, read-write): A function to call when the file or directory changes.
 
-    Event types:
+    **Flags:**
+        - **"none"**
+        - **"watch_mounts"**
+        - **"send_moved"**
+        - **"watch_hard_links"**
+        - **"watch_moves"**
+
+        See `Gio.FileMonitorFlags <https://lazka.github.io/pgi-docs/Gio-2.0/flags.html#Gio.FileMonitorFlags>`_ for more info.
+
+    **Event types:**
         - **"changed"**
         - **"changes_done_hint"**
         - **"moved_out"**
@@ -54,7 +63,7 @@ class FileMonitor(IgnisGObject):
         - **"renamed"**
         - **"moved_in"**
 
-        See `Gio.FileMonitorEvent <https://lazka.github.io/pgi-docs/index.html#Gio-2.0/enums.html#Gio.FileMonitorEvent>`_
+        See `Gio.FileMonitorEvent <https://lazka.github.io/pgi-docs/index.html#Gio-2.0/enums.html#Gio.FileMonitorEvent>`_ for more info.
 
     **Example usage:**
 

ignis/utils/sass.py

@@ -35,14 +35,16 @@ def compile_string(string: str) -> str:
 def sass_compile(path: str = None, string: str = None) -> str:
     """
     Compile a SASS/SCSS file or string.
-    Requires ``dart-sass``.
+    Requires `Dart Sass <https://sass-lang.com/dart-sass/>`_.
 
     Args:
         path (``str``, optional): The path to the SASS/SCSS file.
         string (``str``, optional): A string with SASS/SCSS style.
 
     Raises:
         TypeError: If neither of the arguments is provided.
+        DartSassNotFoundError: If Dart Sass not found.
+        SassCompilationError: If an error occurred while compiling SASS/SCSS.
     """
     if not os.path.exists("/bin/sass"):
         raise DartSassNotFoundError()

ignis/widgets/label.py

@@ -9,9 +9,26 @@ class Label(Gtk.Label, BaseWidget):
     A widget that displays a small amount of text.
 
     Properties:
-        - **justify** (``str``, optional, read-write): The alignment of the lines in the text of the label relative to each other. This does NOT affect the alignment of the label within its allocation. Possible values: ``"left"``, ``"right"``, ``"center"``, ``"fill"``.
-        - **ellipsize** (``str``, optional, read-write): The preferred place to ellipsize the string. Possible values: ``"none"``, ``"start"``, ``"middle"``, ``"end"``.
-        - **wrap_mode** (``str``, optional, read-write): If wrap is set, controls how linewrapping is done. Possible values: ``"word"``, ``"char"``, ``"word_char"``.
+        - **justify** (``str``, optional, read-write): The alignment of the lines in the text of the label relative to each other. This does NOT affect the alignment of the label within its allocation.
+        - **ellipsize** (``str``, optional, read-write): The preferred place to ellipsize the string. Default: ``"none"``.
+        - **wrap_mode** (``str``, optional, read-write): If ``wrap`` is set to ``True``, controls how linewrapping is done. Default: ``"word"``.
+
+    **Justify:**
+        - **"left"** : The text is placed at the left edge of the label.
+        - **"right"** : The text is placed at the right edge of the label.
+        - **"center"** : The text is placed in the center of the label.
+        - **"fill"** : The text is placed is distributed across the label.
+
+    **Ellipsize:**
+        - **"none"** : No ellipsization.
+        - **"start"** : Omit characters at the start of the text.
+        - **"middle"** : Omit characters in the middle of the text.
+        - **"end"** : Omit characters at the end of the text.
+
+    **Wrap mode:**
+        - **"word"** : Wrap lines at word boundaries.
+        - **"char"** : Wrap lines at character boundaries.
+        - **"word_char"** : Wrap lines at word boundaries, but fall back to character boundaries if there is not enough space for a full word.
 
     .. code-block:: python
 

ignis/widgets/picture.py

@@ -15,7 +15,7 @@ class Picture(Gtk.Picture, BaseWidget):
         - **image** (``Union[str, GdkPixbuf.Pixbuf]``, optional, read-write): Icon name, path to an image or ``GdkPixbuf.Pixbuf``.
         - **width** (``int``, optional, read-write): Width of the image.
         - **height** (``int``, optional, read-write): Height of the image.
-        - **content_fit** (``str``, optional, read-write): Controls how a content should be made to fit inside an allocation. Possible values: ``"fill"``, ``"contain"``, ``"cover"``, ``"scale_down"``.
+        - **content_fit** (``str``, optional, read-write): Controls how a content should be made to fit inside an allocation. Default: ``"contain"``.
 
     **Content fit:**
         - **"fill"**: Make the content fill the entire allocation, without taking its aspect ratio in consideration.