Add docs on pagerduty connection (#36636)

airflow/providers/pagerduty/hooks/pagerduty.py

@@ -54,12 +54,29 @@ class PagerdutyHook(BaseHook):
     def get_ui_field_behaviour(cls) -> dict[str, Any]:
         """Returns custom field behaviour."""
         return {
-            "hidden_fields": ["port", "login", "schema", "host"],
+            "hidden_fields": ["port", "login", "schema", "host", "extra"],
             "relabeling": {
                 "password": "Pagerduty API token",
             },
         }
 
+    @classmethod
+    def get_connection_form_widgets(cls) -> dict[str, Any]:
+        """Returns connection widgets to add to connection form."""
+        from flask_appbuilder.fieldwidgets import BS3PasswordFieldWidget
+        from flask_babel import lazy_gettext
+        from wtforms import PasswordField
+        from wtforms.validators import Optional
+
+        return {
+            "routing_key": PasswordField(
+                lazy_gettext("Routing Key"),
+                widget=BS3PasswordFieldWidget(),
+                validators=[Optional()],
+                default=None,
+            ),
+        }
+
     def __init__(self, token: str | None = None, pagerduty_conn_id: str | None = None) -> None:
         super().__init__()
         self.routing_key = None

docs/apache-airflow-providers-pagerduty/connections/index.rst

@@ -0,0 +1,28 @@
+ .. Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+ ..   http://www.apache.org/licenses/LICENSE-2.0
+
+ .. Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+
+
+PagerDuty Connections
+=====================
+
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    *

docs/apache-airflow-providers-pagerduty/connections/pagerdurty.rst

@@ -0,0 +1,45 @@
+ .. Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+ ..   http://www.apache.org/licenses/LICENSE-2.0
+
+ .. Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+
+
+.. _howto/connection:pagerduty:
+
+PagerDuty Connection
+====================
+
+The PagerDuty connection type enables connection to PagerDuty API.
+
+Default Connection IDs
+----------------------
+
+PagerDuty Hook uses parameter ``pagerduty_conn_id`` for Connection IDs and the value of the
+parameter as ``pagerduty_default`` by default.
+
+Configuring the Connection
+--------------------------
+
+Pagerduty API token
+    The API token that will be used for authentication against the PagerDuty API.
+
+Pagerduty Routing key (Integration key)
+    The routing key (also known as Integration key) that will be used to route an event to the corresponding
+    PagerDuty service or rule.
+
+.. note::
+    The Pagerduty Routing key is deprecated.
+    Please use the :ref:`PagerDutyEvents connection <howto/connection:pagerduty-events>` instead.

docs/apache-airflow-providers-pagerduty/connections/pagerduty-events.rst

@@ -0,0 +1,37 @@
+ .. Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+ ..   http://www.apache.org/licenses/LICENSE-2.0
+
+ .. Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+
+
+.. _howto/connection:pagerduty-events:
+
+PagerDuty Events Connection
+===========================
+
+The PagerDuty Events connection type enables connection to PagerDuty Events API.
+
+Default Connection IDs
+----------------------
+
+PagerDuty Events Hook uses parameter ``pagerduty_events_conn_id`` for Connection IDs and the value of the
+parameter as ``pagerduty_events_default`` by default.
+
+Configuring the Connection
+--------------------------
+
+Pagerduty Integration key
+    The integration key that will be used to route an event to the corresponding PagerDuty service or rule.

docs/apache-airflow-providers-pagerduty/index.rst

@@ -49,6 +49,7 @@
     :maxdepth: 1
     :caption: Guides
 
+    Connection types <connections/index>
     Pagerduty Notifications <notifications/pagerduty_notifier_howto_guide>
 
 .. THE REMAINDER OF THE FILE IS AUTOMATICALLY GENERATED. IT WILL BE OVERWRITTEN AT RELEASE TIME!