Application Announcement Hook

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

@@ -0,0 +1,53 @@
+# 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.Service.GITLAB)
+```
+
+```{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`.
+
+### Service
+
+This variable is an enumeration of the class `AppAnnouncemementHook.Service`
+
+It is mandatory to specify this variable so alliance auth contacts the correct API when fetching your repository issues.
+
+```{eval-rst}
+.. autoclass:: allianceauth.services.hooks.AppAnnouncementHook.Service
+  :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