Adding custom hooks

Qtile has added the ability for third party apps to define their own
hooks so this PR adds custom hooks for a number of widgets (e.g. Mpris2
fires hooks on metadata and playback status).

CHANGELOG

@@ -1,3 +1,4 @@
+2023-11-10: [FEATURE] Add custom hooks to certain widgets (refer to docs for more)
 2023-10-16: [FEATURE] Updated `Bluetooth` widget to add context menu
 2023-10-08: [BUGFIX] Fix `BrightnessControl` text display issue in `Bar` mode
 2023-10-07: [BUGFIX] Tooltip position on multiple screens

docs/index.rst

@@ -53,6 +53,7 @@ without needing to recrate the icons themselves. You can see the class :ref:`her
     :hidden:
 
     manual/ref/widgets
+    manual/ref/hooks
     manual/ref/popup
     manual/ref/decorations
     manual/ref/imgmask

docs/manual/ref/hooks.rst

@@ -0,0 +1,5 @@
+=====
+Hooks
+=====
+
+.. qte_hooks:: qtile_extras.hook.subscribe

docs/sphinx_qtile_extras.py

@@ -124,6 +124,13 @@
         {{ caption }}
 
     {% endfor %}
+    {% endif %}
+    {% if hooks %}
+    Available hooks:
+    {% for name in hooks %}
+    - `{{ name}} <hooks.html#qtile_extras.hook.subscribe.{{ name }}>`_
+    {% endfor %}
+
     {% endif %}
     {% if defaults %}
     .. raw:: html
@@ -154,7 +161,7 @@
 
 qtile_hooks_template = Template(
     """
-.. automethod:: libqtile.hook.subscribe.{{ method }}
+.. automethod:: qtile_extras.hook.subscribe.{{ method }}
 """
 )
 
@@ -227,10 +234,11 @@ def make_rst(self):
             "commandable": is_commandable and issubclass(obj, command.base.CommandObject),
             "is_widget": issubclass(obj, widget.base._Widget),
             "experimental": getattr(obj, "_experimental", False),
+            "hooks": getattr(obj, "_hooks", list()),
             "inactive": getattr(obj, "_inactive", False),
             "screenshots": getattr(obj, "_screenshots", list()),
             "dependencies": dependencies,
-            "compatibility": getattr(obj, "_qte_compatibility", False)
+            "compatibility": getattr(obj, "_qte_compatibility", False),
         }
         if context["commandable"]:
             context["commands"] = [
@@ -342,8 +350,19 @@ def make_rst(self):
             yield line
 
 
+class QtileHooks(SimpleDirectiveMixin, Directive):
+    def make_rst(self):
+        module, class_name = self.arguments[0].rsplit(".", 1)
+        obj = import_class(module, class_name)
+        for method in sorted(obj.hooks):
+            rst = qtile_hooks_template.render(method=method)
+            for line in rst.splitlines():
+                yield line
+
+
 def setup(app):
     app.add_directive("qtile_class", QtileClass)
     app.add_directive("qtile_module", QtileModule)
     app.add_directive("list_objects", ListObjects)
     app.add_directive("qte_wallpapers", ListWallpapers)
+    app.add_directive("qte_hooks", QtileHooks)