Merge branch 'master' of gitlab.com:allianceauth/allianceauth into v4.x

docs/development/custom/integrating-services.md

@@ -21,19 +21,19 @@ Typically a service will contain 5 key components:
 The architecture looks something like this:
 
 ```none
-  urls -------▶ Views
-    ▲              |
-    |              |
-    |              ▼
-ServiceHook ----▶ Tasks ----▶ Manager
-    ▲
-    |
-    |
-AllianceAuth
+        urls -------▶ Views
+          ▲              |
+          |              |
+          |              ▼
+      ServiceHook ----▶ Tasks ----▶ Manager
+          ▲
+          |
+          |
+      AllianceAuth
 
 
-Where:
-  Module --▶ Dependency/Import
+    Where:
+        Module --▶ Dependency/Import
 ```
 
 While this is the typical structure of the existing services modules, there is no enforcement of this structure and you are, effectively, free to create whatever architecture may be necessary. A service module need not even communicate with an external service, for example, if similar triggers such as validate_user, delete_user are required for a module it may be convenient to masquerade as a service. Ideally though, using the common structure improves the maintainability for other developers.
@@ -50,23 +50,22 @@ def register_service():
 
 This would register the ExampleService class which would need to be a subclass of `services.hooks.ServiceHook`.
 
-```eval_rst
-.. important::
-    The hook **MUST** be registered in ``yourservice.auth_hooks`` along with any other hooks you are registering for Alliance Auth.
-```
+:::{important}
+The hook **MUST** be registered in ``yourservice.auth_hooks`` along with any other hooks you are registering for Alliance Auth.
+:::
 
 A subclassed `ServiceHook` might look like this:
 
 ```python
 class ExampleService(ServicesHook):
-def __init__(self):
-    ServicesHook.__init__(self)
-    self.urlpatterns = urlpatterns
-    self.service_url = 'http://exampleservice.example.com'
+  def __init__(self):
+      ServicesHook.__init__(self)
+      self.urlpatterns = urlpatterns
+      self.service_url = 'http://exampleservice.example.com'
 
-    """
-    Overload base methods here to implement functionality
-    """
+  """
+  Overload base methods here to implement functionality
+  """
 ```
 
 ### The ServiceHook class
@@ -79,7 +78,7 @@ Instance Variables:
 
 - [self.name](#selfname)
 - [self.urlpatterns](#selfurlpatterns)
-- [self.service_ctrl_template](#selfservice-ctrl-template)
+- [self.service_ctrl_template](#selfservice_ctrl_template)
 
 Properties:
 
@@ -123,7 +122,9 @@ class MyService(ServiceHook):
 
 All of your apps defined urlpatterns will then be included in the `URLconf` when the core application starts.
 
-### Properties
+#### self.service_ctrl_template
+
+This is provided as a courtesy and defines the default template to be used with [render_service_ctrl](#render_service_ctrl). You are free to redefine or not use this variable at all.
 
 #### title
 
@@ -150,12 +151,14 @@ The function should return a boolean, `True` if successfully disabled, `False` o
 Validate the users service account, deleting it if they should no longer have access. The `user` parameter should be a Django User object.
 
 An implementation will probably look like the following:
+
 ```python
 def validate_user(self, user):
 logger.debug('Validating user %s %s account' % (user, self.name))
 if ExampleTasks.has_account(user) and not self.service_active_for_user(user):
     self.delete_user(user, notify_user=True)
 ```
+
 No return value is expected.
 
 This function will be called periodically on all users to validate that the given user should have their current service accounts.
@@ -312,3 +315,9 @@ You should have a look through some of the other service modules before you get
 ## Testing
 
 You will need to add unit tests for all aspects of your service module before it is accepted. Be mindful that you don't actually want to make external calls to the service so you should mock the appropriate components to prevent this behavior.
+
+```{eval-rst}
+.. autoclass:: allianceauth.services.hooks.ServicesHook
+    :members:
+    :undoc-members:
+```