Basic documentation

allianceauth/services/hooks.py

@@ -8,6 +8,7 @@ from django.utils.functional import cached_property
 
 from allianceauth.hooks import get_hooks
 from allianceauth.menu.hooks import MenuItemHook
+from allianceauth.templatetags.admin_status import AppAnnouncementHook
 
 from .models import NameFormatConfig
 
@@ -145,6 +146,16 @@ class MenuItemHook(MenuItemHook):
     def __init_subclass__(cls) -> None:
         return super().__init_subclass__()
 
+class AppAnnouncementHook(AppAnnouncementHook):
+    """
+    AppAnnouncementHook shim to allianceauth.templatetags.admin_status
+
+    :param AppAnnouncementHook: _description_
+    :type AppAnnouncementHook: _type_
+    """
+    def __init_subclass__(cls) -> None:
+        return super().__init_subclass__()
+
 
 class UrlHook:
     """A hook for registering the URLs of a Django app.

allianceauth/templatetags/admin_status.py

@@ -1,6 +1,6 @@
 import logging
 from dataclasses import dataclass
-from enum import Enum, auto
+from enum import Enum
 from urllib.parse import quote_plus
 
 import requests
@@ -36,14 +36,24 @@ GITLAB_AUTH_ANNOUNCEMENT_ISSUES_URL = (
 
 logger = logging.getLogger(__name__)
 
-class RepositoryKind(Enum):
-    """What kind of repository is being used"""
-    GITLAB = auto()
-    GITHUB = auto()
-
 @dataclass
 class AppAnnouncementHook:
-    """Hook for an application to send GitHub/GitLab issues as announcements"""
+    """
+    A hook for an application to send GitHub/GitLab issues as announcements on the dashboard
+
+    Args:
+        - app_name: The name of your application
+        - repository_namespace: The namespace of the remote repository of your application source code.
+            It should look like `<username>/<application_name>`.
+        - repository_kind: Enumeration to determine if your repository is a GitHub or GitLab repository.
+        - label: The label applied to issues that should be seen as announcements, case-sensitive.
+            Default value: `announcement`
+    """
+    class RepositoryKind(Enum):
+        """Simple enumeration to determine which api should be called to access issues"""
+        GITLAB = "gitlab"
+        GITHUB = "github"
+
     app_name: str
     repository_namespace: str
     repository_kind: RepositoryKind
@@ -56,9 +66,9 @@ class AppAnnouncementHook:
         be displayed.
         """
         match self.repository_kind:
-            case RepositoryKind.GITHUB:
+            case AppAnnouncementHook.RepositoryKind.GITHUB:
                 announcement_list = self._get_github_announcement_list()
-            case RepositoryKind.GITLAB:
+            case AppAnnouncementHook.RepositoryKind.GITLAB:
                 announcement_list = self._get_gitlab_announcement_list()
             case _:
                 return []
@@ -95,11 +105,11 @@ class AppAnnouncementHook:
 
 @hooks.register("app_announcement_hook")
 def test_hook():
-    return AppAnnouncementHook("test GitLab app", "r0kym/allianceauth-example-plugin", RepositoryKind.GITLAB)
+    return AppAnnouncementHook("test GitLab app", "r0kym/allianceauth-example-plugin", AppAnnouncementHook.RepositoryKind.GITLAB)
 
 @hooks.register("app_announcement_hook")
 def test_hook_2():
-    return AppAnnouncementHook("test GitHub app", "r0kym/test", RepositoryKind.GITHUB)
+    return AppAnnouncementHook("test GitHub app", "r0kym/test", AppAnnouncementHook.RepositoryKind.GITHUB)
 
 @register.simple_tag()
 def decimal_widthratio(this_value, max_value, max_width) -> str:

docs/development/custom/app-announcement-hooks.md

@@ -0,0 +1,52 @@
+# Announcement Hooks
+
+This hook allows the issues opened on your application repository to be displayed on the alliance auth front page to
+administrators.
+
+![app_announcement_hook_example](img/app_announcement_hook_example.png)
+
+To register an AppAnnouncementHook class, you would do the following:
+
+```python
+from allianceauth import hooks
+from allianceauth.services.hooks import AppAnnouncementHook
+
+@hooks.register('app_announcement_hook')
+def announcement_hook():
+    return AppAnnouncementHook("Your app name", "USERNAME/REPOSITORY_NAME", AppAnnouncementHook.RepositoryKind.GITLAB)
+```
+
+The `AppAnnouncementHook` class will
+
+```{eval-rst}
+.. autoclass:: allianceauth.services.hooks.AppAnnouncementHook
+  :members: __init__
+  :undoc-members:
+```
+
+## Parameters
+
+### app_name
+
+The name of your application.
+
+### repository_namespace
+
+Here you should enter the namespace of your repository.
+The structure stays the same for both GitHub and GitLab repositories. \
+A repository with the url `https://gitlab.com/username/appname` will have a namespace of `username/appname`.
+
+### repository_kind
+
+This variable is an enumeration of the class `AppAnnouncemementHook.RepositoryKind`
+
+```{eval-rst}
+.. autoclass:: allianceauth.services.hooks.AppAnnouncementHook.RepositoryKind
+  :members: GITLAB, GITHUB
+  :undoc-members:
+```
+
+### label
+
+The label that will determine if issues should be seen as an announcement.
+This value is case-sensitive and the default value is `"announcement"`.

docs/development/custom/index.md

@@ -8,6 +8,7 @@ This section describes how to extend **Alliance Auth** with custom apps, service
 integrating-services
 menu-hooks
 url-hooks
+app-announcement-hooks
 logging
 custom-themes
 aa-framework