Add documentation for the PowerBIDatasetRefresh Operator. (apache#42754)

* Add documentation for PowerBI Dataset Refresh Operator

* Add the link to powerbi documentation in operator class

* Refactor rst files

* Add how-to-guide in provider.yaml

* add files created in create-missing-init-py-files-tests hook

* Fix to pass breeze unit tests

* Fix to pass breeze unit tests

* Fix operator documentation path

* remove pre-commit generated files

docs/apache-airflow-providers-microsoft-azure/connections/powerbi.rst

@@ -0,0 +1,60 @@
+.. 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:powerbi:
+
+Microsoft Power BI Connection
+=============================
+
+The Microsoft Power BI connection type enables the Power BI Integrations.
+
+The :class:`~airflow.providers.microsoft.azure.hooks.powerbi.PowerBIHook` and :class:`~airflow.providers.microsoft.azure.operators.powerbi.PowerBIDatasetOperator` requires a connection of type ``powerbi`` to authenticate with the Power BI.
+
+Authenticating to Power BI
+-------------------------------
+
+1. Use `token credentials
+   <https://docs.microsoft.com/en-us/azure/developer/python/azure-sdk-authenticate?tabs=cmd#authenticate-with-token-credentials>`_
+   i.e. add specific credentials (client_id, client_secret, tenant_id) to the Airflow connection.
+
+Default Connection IDs
+----------------------
+
+All hooks and operators related to Microsoft Power BI use ``powerbi_default`` by default.
+
+Configuring the Connection
+--------------------------
+
+Client ID
+    Specify the ``client_id`` used for the initial connection.
+    This is needed for *token credentials* authentication mechanism.
+
+
+Client Secret
+    Specify the ``client_secret`` used for the initial connection.
+    This is needed for *token credentials* authentication mechanism.
+
+
+Tenant ID
+    Specify the ``tenant_id`` used for the initial connection.
+    This is needed for *token credentials* authentication mechanism.
+
+.. spelling:word-list::
+
+    Entra

docs/apache-airflow-providers-microsoft-azure/operators/powerbi.rst

@@ -0,0 +1,50 @@
+ .. 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.
+
+
+Microsoft Power BI Operators
+=============================
+`Microsoft Power BI <https://powerbi.microsoft.com/>`__, is a unified, scalable platform for self-service and enterprise business intelligence(BI).
+
+
+Prerequisite Tasks
+^^^^^^^^^^^^^^^^^^
+
+.. include:: /operators/_partials/prerequisite_tasks.rst
+
+.. _howto/operator:PowerBIDatasetRefreshOperator:
+
+PowerBIDatasetRefreshOperator
+----------------------------------
+
+To trigger a refresh for the specified dataset from the specified workspace, use the :class:`~airflow.providers.microsoft.azure.operators.powerbi.PowerBIDatasetRefreshOperator`.
+
+
+.. exampleinclude:: /../../providers/tests/system/microsoft/azure/example_powerbi_dataset_refresh.py
+    :language: python
+    :dedent: 0
+    :start-after: [START howto_operator_powerbi_refresh_async]
+    :end-before: [END howto_operator_powerbi_refresh_async]
+
+Reference
+---------
+
+For further information, look at:
+
+* `Use the Microsoft Graph API <https://learn.microsoft.com/en-us/graph/use-the-api/>`__
+* `Using the Power BI REST APIs <https://learn.microsoft.com/en-us/rest/api/power-bi/>`__
+* `Using the Fabric REST APIs <https://learn.microsoft.com/en-us/rest/api/fabric/articles/using-fabric-apis/>`__

providers/src/airflow/providers/microsoft/azure/operators/powerbi.py

@@ -52,6 +52,10 @@ class PowerBIDatasetRefreshOperator(BaseOperator):
     """
     Refreshes a Power BI dataset.
 
+    .. seealso::
+        For more information on how to use this operator, take a look at the guide:
+        :ref:`howto/operator:PowerBIDatasetRefreshOperator`
+
     :param dataset_id: The dataset id.
     :param group_id: The workspace id.
     :param conn_id: Airflow Connection ID that contains the connection information for the Power BI account used for authentication.

providers/src/airflow/providers/microsoft/azure/provider.yaml

@@ -190,6 +190,8 @@ integrations:
     tags: [azure]
   - integration-name: Microsoft Power BI
     external-doc-url: https://learn.microsoft.com/en-us/rest/api/power-bi/
+    how-to-guide:
+      - /docs/apache-airflow-providers-microsoft-azure/operators/powerbi.rst
     tags: [azure]
 
 operators: