docs: split homepage, add tasks docs

.env.example

@@ -62,7 +62,7 @@ CONFLUENCE_MOCK_CREATE_POSTMORTEM=True
 ## PagerDuty settings (optional) ## (5)
 
 ENABLE_PAGERDUTY=False
-PAGERDUTY_ACCOUNT_EMAIL="admin@manomano.com"
+PAGERDUTY_ACCOUNT_EMAIL="admin@mycompany.com"
 PAGERDUTY_API_KEY="u+XXXXXXXXXXXXXXXX-X"
 PAGERDUTY_URL="https://api.pagerduty.com"
 

docs/Deploy/XX-settings.md

@@ -31,8 +31,6 @@ Redis DBs:
 
 ## FireFighter settings
 
-
-
 - [`BASE_URL`][firefighter.firefighter.settings.settings_utils.BASE_URL]
 - [`FF_ROLE_REMINDER_MIN_DAYS_INTERVAL`][firefighter.firefighter.settings.components.common.FF_ROLE_REMINDER_MIN_DAYS_INTERVAL]
 - [`FF_USER_ID_HEADER`][firefighter.firefighter.settings.components.common.FF_USER_ID_HEADER]
@@ -85,10 +83,10 @@ See [django-oauth2-codeflow](https://gitlab.com/systra/qeto/lib/django-oauth2-au
 
 ## Pagerduty integration
 
-- `ENABLE_PAGERDUTY`: default: `False`
-- `PAGERDUTY_API_KEY`
-- `PAGERDUTY_ACCOUNT_EMAIL`
-- `PAGERDUTY_URL`: default: `https://api.pagerduty.com`
+- [`ENABLE_PAGERDUTY`][firefighter.firefighter.settings.components.pagerduty.ENABLE_PAGERDUTY]: default: `False`
+- [`PAGERDUTY_API_KEY`][firefighter.firefighter.settings.components.pagerduty.PAGERDUTY_API_KEY]
+- [`PAGERDUTY_ACCOUNT_EMAIL`][firefighter.firefighter.settings.components.pagerduty.PAGERDUTY_ACCOUNT_EMAIL]
+- [`PAGERDUTY_URL`][firefighter.firefighter.settings.components.pagerduty.PAGERDUTY_URL]: default: `https://api.pagerduty.com`
 
 ## Other settings
 

docs/Deploy/XX-tasks.md

@@ -0,0 +1,28 @@
+# Celery tasks
+
+This project uses [Celery](https://docs.celeryproject.org/en/stable/) to run asynchronous tasks.
+
+## Running
+
+You will need to run a Celery worker to run the tasks, and a Celery beat to schedule them.
+
+```bash
+pdm run celery-worker
+```
+
+```bash
+pdm run celery-beat
+```
+
+!!! note
+    A Django management command is also available to run a specific task:
+
+    ```bash
+    pdm run ff-manage task <task_name>
+    ```
+
+## Scheduling tasks
+
+By default, no tasks are scheduled.
+
+You can schedule tasks through the Django admin interface.

docs/Usage/integrations.md

@@ -0,0 +1,65 @@
+
+# Integrations
+
+## :simple-pagerduty: PagerDuty
+
+### Features
+
+Expose the current on-call schedule, and allow anyone to escalate to PagerDuty.
+
+![PagerDuty integration](../assets/screenshots/pagerduty_web_oncall_overview.png)
+_Exposing the on-call schedule, even for users with no PagerDuty access._
+
+![PagerDuty integration](../assets/screenshots/pagerduty_web_oncall_overview.png)
+_Trigger a PagerDuty incident from the Web UI, even with no PagerDuty access._
+
+![PagerDuty integration](../assets/screenshots/pagerduty_slack_trigger.png)
+_In a Slack conversation about an incident, anyone can escalate to PagerDuty, with `/incident oncall`._
+
+### Tasks
+
+Tasks are provided to regularly sync the on-call schedules, services and users from PagerDuty, as well as a task to trigger PagerDuty incidents.
+
+If Confluence is enabled, there is a task to export the on-call schedule to a Confluence page set with environment variable `CONFLUENCE_ON_CALL_PAGE_ID`.
+
+See the [available PagerDuty tasks][firefighter.pagerduty.tasks] that can be [scheduled from the Back-Office](../Deploy/XX-tasks.md).
+
+### Settings and configuration
+
+[Basic configuration with environment variables](../Deploy/XX-settings.md#pagerduty-integration).
+
+No Back-Office configuration.
+
+## :fontawesome-brands-confluence: Confluence
+
+!!! warning
+    This integration is disabled by default, and is not yet documented.
+    It is specific to our internal use case.
+
+## :fontawesome-brands-slack: Slack
+
+### Tasks
+
+Tasks are provided to regularly sync users, conversations, usergroups and channel members from Slack.
+
+See the [available Slack tasks][firefighter.slack.tasks] that can be [scheduled from the Back-Office](../Deploy/XX-tasks.md).
+
+### Settings and configuration
+
+See [Slack environment variables settings](../Deploy/XX-settings.md#slack-integration).
+
+#### Back-Office configuration
+
+You can add custom tags to Slack conversations in the back-office.
+
+Some tags have special meaning:
+
+- `tech_incidents`: send incidents notifications to the channel
+- `dev_firefighter`: Where users can get help with the bot. Will be shown in `/incident help` for instance.
+- `it_deploy`: Where the bot send notifications for deployment freezes.
+
+## :fontawesome-brands-jira: Jira
+
+!!! warning
+    This integration is disabled by default, and is not yet documented.
+    It is specific to our internal use case.

docs/index.md

@@ -24,7 +24,7 @@
 
     Expose your on-call schedule, and allow anyone to escalate to PagerDuty.
 
-    <!-- [:octicons-arrow-right-24: Reference](#) -->
+    [:octicons-arrow-right-24: Learn more](Usage/integrations.md#pagerduty)
 
 -   :fontawesome-brands-jira:{ .lg .middle } __Follow on Jira__ _(optional)_
 
@@ -56,53 +56,3 @@
     Please open an issue if you have any question, or if you need help.
 
     The [FAQ](FAQ.md) may also answer some of your questions.
-
-## Integrations
-
-### PagerDuty
-
-#### Features
-
-Expose the current on-call schedule, and allow anyone to escalate to PagerDuty.
-
-![PagerDuty integration](assets/screenshots/pagerduty_web_oncall_overview.png)
-_Exposing the on-call schedule, even for users with no PagerDuty access._
-
-![PagerDuty integration](assets/screenshots/pagerduty_web_oncall_overview.png)
-_Trigger a PagerDuty incident from the Web UI, even with no PagerDuty access._
-
-![PagerDuty integration](assets/screenshots/pagerduty_slack_trigger.png)
-_In a Slack conversation about an incident, anyone can escalate to PagerDuty, with `/incident oncall`._
-
-
-#### Tasks
-
-Tasks are provided to regularly sync the on-call schedules, services and users from PagerDuty, as well as a task to trigger PagerDuty incidents.
-<!-- See FIXME links to reference. -->\
-
-
-If Confluence is enabled, there is a task to export the on-call schedule to a Confluence page set with `CONFLUENCE_ON_CALL_PAGE_ID`.
-
-#### Settings and configuration
-
-Basic ENV configuration.
-
-No Back-Office configuration.
-
-### Confluence
-
-### Slack
-
-#### Settings and configuration
-
-See settings in [slack.py][firefighter.firefighter.settings.components.slack]
-
-##### Back-Office configuration
-
-You can add custom tags to Slack conversations in the back-office.
-
-Some tags have special meaning:
-
-- `tech_incidents`: send incidents notifications to the channel
-- `dev_firefighter`: Where users can get help with the bot. Will be shown in `/incident help` for instance.
-- `it_deploy`: Where the bot send notifications for deployment freezes.

mkdocs.yml

@@ -1,7 +1,7 @@
 ---
 site_name: FireFighter Docs
 site_description: FireFighter is ManoMano's incident management tool, built on top of Slack and Jira, with Django and Python.
-site_url: https:/manomanotech.github.io/firefighter-incident/
+site_url: https://manomanotech.github.io/firefighter-incident/
 
 repo_url: https://github.com/ManoManoTech/firefighter-incident
 repo_name: ManoManoTech/firefighter-incident
@@ -88,13 +88,16 @@ nav:
       - License: license.md
       - FAQ: FAQ.md
   - Usage:
+      - Integrations: Usage/integrations.md
       - Deployment:
           - Deploy/00-intro.md
+          - Settings:
+              - Deploy/XX-settings.md
+              - Deploy/XX-custom-settings.md
           - Deploy/XX-auth.md
-          - Deploy/XX-custom-settings.md
-          - Deploy/XX-i18n-l10.md
+          - Translation and timezone: Deploy/XX-i18n-l10.md
           - Deploy/XX-logs-traces.md
-          - Deploy/XX-settings.md
+          - Deploy/XX-tasks.md
           - Deploy/XX-support-policy.md
 
   - Development:

src/firefighter/firefighter/settings/components/celery.py

@@ -28,9 +28,9 @@
     "result_serializer": "json",
     # http://docs.celeryproject.org/en/latest/userguide/configuration.html#task-time-limit
     # set to whatever value is adequate in your circumstances
-    "task_time_limit": 3 * 60,
+    "task_time_limit": 3 * 60,  # in seconds
     # http://docs.celeryproject.org/en/latest/userguide/configuration.html#task-soft-time-limit
-    "task_soft_time_limit": 2 * 60,
+    "task_soft_time_limit": 2 * 60,  # in seconds
     # http://docs.celeryproject.org/en/latest/userguide/configuration.html#beat-scheduler
     "beat_scheduler": "django_celery_beat.schedulers:DatabaseScheduler",
     # https://docs.celeryq.dev/en/stable/userguide/configuration.html#std-setting-broker_connection_retry

src/firefighter/firefighter/settings/components/pagerduty.py

@@ -4,10 +4,14 @@
 from firefighter.firefighter.settings.settings_utils import config
 
 ENABLE_PAGERDUTY: bool = config("ENABLE_PAGERDUTY", cast=bool, default=False)
+"""Enable PagerDuty integration."""
 
 if ENABLE_PAGERDUTY:
     INSTALLED_APPS.append("firefighter.pagerduty")
 
     PAGERDUTY_API_KEY: str = config("PAGERDUTY_API_KEY")
+    """PagerDuty API key."""
     PAGERDUTY_ACCOUNT_EMAIL: str = config("PAGERDUTY_ACCOUNT_EMAIL")
+    """PagerDuty account email, linked to the API key."""
     PAGERDUTY_URL: str = config("PAGERDUTY_URL", default="https://api.pagerduty.com")
+    """PagerDuty API URL."""

src/firefighter/pagerduty/tasks/__init__.py

@@ -1,3 +1,4 @@
+"""PagerDuty Celery tasks."""
 from __future__ import annotations
 
 from firefighter.pagerduty.tasks.fetch_oncall import fetch_oncalls

src/firefighter/pagerduty/tasks/fetch_oncall.py

@@ -21,6 +21,9 @@
 
 @celery_app.task(name="pagerduty.fetch_oncalls")
 def fetch_oncalls() -> None:
+    """Celery task to fetch PagerDuty oncalls and save them in the database.
+    Will try to update services, users, schedules and escalation policies if needed.
+    """
     services = pagerduty_service.get_all_oncalls()
     return create_oncalls(services)
 

src/firefighter/pagerduty/tasks/fetch_services.py

@@ -14,6 +14,7 @@
 @shared_task(name="pagerduty.fetch_services")
 @transaction.atomic
 def fetch_services() -> None:
+    """Celery task to fetch PagerDuty services and save them in the database."""
     fetched_services_key = []
     for service in pagerduty_service.client.session.iter_all("services"):
         fetched_services_key.append(service["id"])

src/firefighter/pagerduty/tasks/fetch_users.py

@@ -13,6 +13,7 @@
 
 @shared_task(name="pagerduty.fetch_users")
 def fetch_users(*, delete_stale_user: bool = True) -> None:
+    """Celery task to fetch PagerDuty users and save them in the database."""
     fetched_users_id = []
     for user in pagerduty_service.client.get_all_users():
         logger.debug(user)

src/firefighter/pagerduty/tasks/trigger_oncall.py

@@ -27,7 +27,9 @@ def trigger_oncall(
     incident_id: int | None = None,
     triggered_by: User | None = None,
 ) -> PagerDutyIncident:
-    """XXX Trigger from PD user if it exists, instead of admin.
+    """Celery task to trigger an on-call in PagerDuty, from a FireFighter incident.
+
+    XXX Trigger from PD user if it exists, instead of admin.
     XXX Should be a service ID instead of a service object.
     """
     service = oncall_service

src/firefighter/raid/forms.py

@@ -444,7 +444,7 @@ def send_message_to_watchers(
             )
         except SlackApiError:
             logger.warning(
-                f"Couldn't send private message to reporter with jira_id={watcher}"
+                f"Couldn't send private message to reporter with jira_id={watcher.get('accountId', watcher)}"
             )
     return True