docs: add documentation

Author: Kl0ven

.github/workflows/documentation.yaml

@@ -0,0 +1,28 @@
+name: Docs
+on:
+  push:
+    branches: [main]
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.10"
+      - name: Run image
+        uses: abatilo/actions-poetry@v2.0.0
+        with:
+          poetry-version: 1.3
+      - name: Install dependencies
+        run: poetry install
+      - name: Sphinx build
+        run: |
+          poetry run sphinx-build docs public
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.ref == 'refs/heads/main' }}
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: public/

.pre-commit-config.yaml

@@ -20,10 +20,7 @@ repos:
     rev: 0.1.2
     hooks:
       - id: pylama
-        args: # arguments to configure black
-          - --max-line-length=119
-          # due to https://github.com/PyCQA/pycodestyle/issues/373
-          - -i E203
+        additional_dependencies: [toml, mypy, eradicate, pydocstyle==6.1.1]
 
   - repo: https://github.com/pycqa/isort
     rev: 5.12.0

README.md

@@ -9,10 +9,10 @@ This project aims to provide dynamic sampling without relying on Sentry Dynamic
 
 It work by installing the library [sentry-dynamic-sampling-lib](https://github.com/SpikeeLabs/sentry-dynamic-sampling-lib) on each project that use sentry. This lib hooks into the sentry callback to change the sampling rate. To get the rate the lib calls this service.
 
+Docs : [here](https://spikeelabs.github.io/sentry-dynamic-sampling-controller/)
 
 
-
-## Development
+## Install
 ```bash
 # install deps
 poetry install
@@ -40,3 +40,10 @@ python manage.py loadpermissions
 python manage.py runserver
 
 ```
+
+
+## Develop
+```bash
+# build docs
+sphinx-build -b html docs public
+```

controller/__init__.py

@@ -1,3 +1,4 @@
+"""Controller."""
 from controller.celery import app as celery_app
 
 __all__ = ("celery_app",)

controller/celery.py

@@ -1,3 +1,4 @@
+"""Celery."""
 import os
 
 from celery import Celery

controller/sentry/__init__.py

@@ -0,0 +1 @@
+"""Sentry App."""

controller/sentry/admin.py

@@ -1,3 +1,6 @@
+"""Admin."""
+from typing import TYPE_CHECKING, Optional
+
 from admin_action_tools import (
     ActionFormMixin,
     AdminConfirmMixin,
@@ -22,6 +25,11 @@
 from controller.sentry.models import App, Event, Project
 from controller.sentry.utils import invalidate_cache
 
+if TYPE_CHECKING:  # pragma: no cover  # pragma: no cover
+    from django.db.models import QuerySet
+    from django.forms import ModelForm
+    from django.http import HttpRequest
+
 
 @admin.register(Project)
 class ProjectAdmin(
@@ -32,6 +40,7 @@ class ProjectAdmin(
     DynamicArrayMixin,
     admin.ModelAdmin,
 ):
+    """Project Admin."""
 
     list_display = [
         "sentry_id",
@@ -61,6 +70,14 @@ class ProjectAdmin(
     inlines = [ProjectEventInline]
 
     def get_chart_data(self, sentry_id):
+        """This method return the chart data.
+
+        Args:
+            sentry_id (str): sentry id
+
+        Returns:
+            Optional[Tuple[dict, dict]]: tuple of data and options
+        """
         project = Project.objects.get(sentry_id=sentry_id)
         if project.detection_result is None:
             return None
@@ -123,6 +140,7 @@ class EventAdmin(
     PrettyTypeMixin,
     admin.ModelAdmin,
 ):
+    """Event Admin."""
 
     list_display = ["reference", "pretty_type", "timestamp", "get_project"]
 
@@ -150,6 +168,8 @@ class AppAdmin(
     DynamicArrayMixin,
     admin.ModelAdmin,
 ):
+    """App Admin."""
+
     read_only_fields = ["last_seen"]
 
     list_display = [
@@ -219,22 +239,48 @@ class AppAdmin(
     inlines = [AppEventInline]
 
     @admin.display(description="Spamming Sentry")
-    def get_event_status(self, obj):
+    def get_event_status(self, obj: App) -> str:
+        """This method return a pretty event status html string.
+
+        Args:
+            obj (App): The app
+
+        Returns:
+            str: The pretty status
+        """
         text = '<b style="color:{};">{}</b>'
         if obj.project and (event := obj.project.events.last()):
             if event.type == EventType.DISCARD:
                 return format_html(text, "green", "No")
             return format_html(text, "red", "Yes")
         return format_html(text, "gray", "Pending")
 
-    def get_changelist_actions(self, request):
+    def get_changelist_actions(self, request: "HttpRequest") -> list[str]:
+        """This method return allowed changelist actions.
+
+        Args:
+            request (HttpRequest): The request
+
+        Returns:
+            list[str]: All possible actions
+        """
         allowed_actions = []
         for action in self.changelist_actions:
             if getattr(self, f"has_{action}_permission")(request):
                 allowed_actions.append(action)
         return allowed_actions
 
-    def get_change_actions(self, request, object_id, form_url):
+    def get_change_actions(self, request: "HttpRequest", object_id: str, form_url: Optional[str]) -> list[str]:
+        """This method return allowed change actions.
+
+        Args:
+            request (HttpRequest): The request
+            object_id (str): The App reference
+            form_url (Optional[str]): The form_url
+
+        Returns:
+            list[str]: All possible actions
+        """
         allowed_actions = []
         for action in self.change_actions:
             if getattr(self, f"has_{action}_permission")(request):
@@ -246,7 +292,19 @@ def get_change_actions(self, request, object_id, form_url):
     @add_form_to_action(BumpForm)
     @confirm_action()
     @admin.action(description="Bump Sample Rate")
-    def bump_sample_rate(self, request, queryset, form: BumpForm = None):  # pylint: disable=unused-argument
+    def bump_sample_rate(
+        self,
+        request: "HttpRequest",
+        queryset: "QuerySet[App]",
+        form: BumpForm = None,  # pylint: disable=unused-argument
+    ) -> None:
+        """This method is responsible for the bump sample rate action.
+
+        Args:
+            request (HttpRequest): The request
+            queryset (QuerySet[App]): The Apps to change
+            form (BumpForm): The form
+        """
         new_date = timezone.now() + form.cleaned_data["duration"]
         queryset.update(
             active_sample_rate=form.cleaned_data["new_sample_rate"],
@@ -257,8 +315,15 @@ def bump_sample_rate(self, request, queryset, form: BumpForm = None):  # pylint:
 
     bump_sample_rate.allowed_permissions = ("bump_sample_rate",)
 
-    def has_bump_sample_rate_permission(self, request):
-        """Does the user have the bump permission?"""
+    def has_bump_sample_rate_permission(self, request: "HttpRequest") -> bool:
+        """This method return True if the user have the permission for bump sample rate action.
+
+        Args:
+            request (HttpRequest): The request
+
+        Returns:
+            bool: Is allowed
+        """
         opts = self.opts
         codename = get_permission_codename("bump_sample_rate", opts)
 
@@ -269,7 +334,19 @@ def has_bump_sample_rate_permission(self, request):
     @takes_instance_or_queryset
     @add_form_to_action(MetricForm)
     @admin.action(description="Enable/Disable Metrics Collection")
-    def enable_disable_metrics(self, request, queryset, form: MetricForm = None):  # pylint: disable=unused-argument
+    def enable_disable_metrics(
+        self,
+        request: "HttpRequest",
+        queryset: "QuerySet[App]",
+        form: MetricForm = None,  # pylint: disable=unused-argument
+    ) -> None:
+        """This method is responsible for the enable/disable metrics action.
+
+        Args:
+            request (HttpRequest): The request
+            queryset (QuerySet[App]): The Apps to change
+            form (MetricForm): The form
+        """
         metrics = form.cleaned_data["metrics"]
         app: App
         for app in queryset:
@@ -280,8 +357,15 @@ def enable_disable_metrics(self, request, queryset, form: MetricForm = None):  #
 
     enable_disable_metrics.allowed_permissions = ("enable_disable_metrics",)
 
-    def has_enable_disable_metrics_permission(self, request):
-        """Does the user have the enable_disable_metrics permission?"""
+    def has_enable_disable_metrics_permission(self, request: "HttpRequest") -> bool:
+        """This method return True if the user have the permission for enable/disable metrics action.
+
+        Args:
+            request (HttpRequest): The request
+
+        Returns:
+            bool: Is allowed
+        """
         opts = self.opts
         codename = get_permission_codename("enable_disable_metrics", opts)
 
@@ -291,14 +375,27 @@ def has_enable_disable_metrics_permission(self, request):
     @takes_instance_or_queryset
     @confirm_action(display_queryset=False)
     @admin.action(description="Panic")
-    def panic(self, request, queryset):  # pylint: disable=unused-argument
+    def panic(self, request: "HttpRequest", queryset: "QuerySet[App]") -> None:  # pylint: disable=unused-argument
+        """This method activate the panic mode.
+
+        Args:
+            request (HttpRequest): The request
+            queryset (QuerySet[App]): All the Apps (unused)
+        """
         cache.set(settings.PANIC_KEY, True, timeout=None)
 
     panic.allowed_permissions = ("panic",)
     panic.attrs = {"style": "background-color: red;"}
 
-    def has_panic_permission(self, request):
-        """Does the user have the panic permission?"""
+    def has_panic_permission(self, request: "HttpRequest") -> bool:
+        """This method return True if the user have the permission for panic action.
+
+        Args:
+            request (HttpRequest): The request
+
+        Returns:
+            bool: Is allowed
+        """
         panic = cache.get(settings.PANIC_KEY)
         opts = self.opts
         codename = get_permission_codename("panic", opts)
@@ -307,20 +404,41 @@ def has_panic_permission(self, request):
     @takes_instance_or_queryset
     @confirm_action(display_queryset=False)
     @admin.action(description="UnPanic")
-    def unpanic(self, request, queryset):  # pylint: disable=unused-argument
+    def unpanic(self, request: "HttpRequest", queryset: "QuerySet[App]") -> None:  # pylint: disable=unused-argument
+        """This method deactivate the panic mode.
+
+        Args:
+            request (HttpRequest): The request
+            queryset (QuerySet[App]): All the Apps (unused)
+        """
         cache.delete(settings.PANIC_KEY)
 
     unpanic.allowed_permissions = ("unpanic",)
     unpanic.attrs = {"style": "background-color: green;"}
 
-    def has_unpanic_permission(self, request):
-        """Does the user have the panic permission?"""
+    def has_unpanic_permission(self, request: "HttpRequest") -> bool:
+        """This method return True if the user have the permission for unpanic action.
+
+        Args:
+            request (HttpRequest): The request
+
+        Returns:
+            bool: Is allowed
+        """
         panic = cache.get(settings.PANIC_KEY)
         opts = self.opts
         codename = get_permission_codename("panic", opts)
         return panic and request.user.has_perm("%s.%s" % (opts.app_label, codename))
 
     # Save model
-    def save_model(self, request, obj, form, change) -> None:
+    def save_model(self, request: "HttpRequest", obj: App, form: "ModelForm", change: bool) -> None:
+        """This method is responsible to save app in the admin.
+
+        Args:
+            request (HttpRequest): The request
+            obj (App): The app to save
+            form (ModelForm): form
+            change (bool): change
+        """
         invalidate_cache(f"/sentry/apps/{obj.reference}/")
         return super().save_model(request, obj, form, change)

controller/sentry/apps.py

@@ -1,7 +1,10 @@
+"""Sentry App."""
 from django.apps import AppConfig
 from django.utils.translation import gettext_lazy as _
 
 
 class SentryConfig(AppConfig):
+    """Sentry App Config."""
+
     name = "controller.sentry"
     verbose_name = _("sentry")