docs: Formatting change from HTML to markdown; Additional clarifications (#174)

* 🦉 Updates from OwlBot

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

chore: use gapic-generator-python 0.63.2
docs: add generated snippets

PiperOrigin-RevId: 427792504

Source-Link: googleapis/googleapis@55b9e1e

Source-Link: https://github.com/googleapis/googleapis-gen/commit/bf4e86b753f42cb0edb1fd51fbe840d7da0a1cde
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiYmY0ZTg2Yjc1M2Y0MmNiMGVkYjFmZDUxZmJlODQwZDdkYTBhMWNkZSJ9

🦉 Updates from OwlBot

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

docs: Formatting change from HTML to markdown; Additional clarifications

PiperOrigin-RevId: 427761663

Source-Link: googleapis/googleapis@46c5d65

Source-Link: https://github.com/googleapis/googleapis-gen/commit/f86bdde29db53037289ac2daa2047779d891d34e
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiZjg2YmRkZTI5ZGI1MzAzNzI4OWFjMmRhYTIwNDc3NzlkODkxZDM0ZSJ9

* 🦉 Updates from OwlBot

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

Author: gcf-owl-bot[bot]

google/cloud/billing/budgets_v1/services/budget_service/async_client.py

@@ -239,7 +239,7 @@ def sample_create_budget():
                 # Make the request
                 response = client.create_budget(request=request)
 
-                # Handle response
+                # Handle the response
                 print(response)
 
         Args:
@@ -348,7 +348,7 @@ def sample_update_budget():
                 # Make the request
                 response = client.update_budget(request=request)
 
-                # Handle response
+                # Handle the response
                 print(response)
 
         Args:
@@ -476,7 +476,7 @@ def sample_get_budget():
                 # Make the request
                 response = client.get_budget(request=request)
 
-                # Handle response
+                # Handle the response
                 print(response)
 
         Args:
@@ -587,6 +587,8 @@ def sample_list_budgets():
 
                 # Make the request
                 page_result = client.list_budgets(request=request)
+
+                # Handle the response
                 for response in page_result:
                     print(response)
 
@@ -695,7 +697,7 @@ def sample_delete_budget():
                 )
 
                 # Make the request
-                response = client.delete_budget(request=request)
+                client.delete_budget(request=request)
 
         Args:
             request (Union[google.cloud.billing.budgets_v1.types.DeleteBudgetRequest, dict]):

google/cloud/billing/budgets_v1/services/budget_service/client.py

@@ -434,7 +434,7 @@ def sample_create_budget():
                 # Make the request
                 response = client.create_budget(request=request)
 
-                # Handle response
+                # Handle the response
                 print(response)
 
         Args:
@@ -544,7 +544,7 @@ def sample_update_budget():
                 # Make the request
                 response = client.update_budget(request=request)
 
-                # Handle response
+                # Handle the response
                 print(response)
 
         Args:
@@ -663,7 +663,7 @@ def sample_get_budget():
                 # Make the request
                 response = client.get_budget(request=request)
 
-                # Handle response
+                # Handle the response
                 print(response)
 
         Args:
@@ -765,6 +765,8 @@ def sample_list_budgets():
 
                 # Make the request
                 page_result = client.list_budgets(request=request)
+
+                # Handle the response
                 for response in page_result:
                     print(response)
 
@@ -864,7 +866,7 @@ def sample_delete_budget():
                 )
 
                 # Make the request
-                response = client.delete_budget(request=request)
+                client.delete_budget(request=request)
 
         Args:
             request (Union[google.cloud.billing.budgets_v1.types.DeleteBudgetRequest, dict]):

google/cloud/billing/budgets_v1beta1/services/budget_service/async_client.py

@@ -214,10 +214,10 @@ async def create_budget(
         timeout: float = None,
         metadata: Sequence[Tuple[str, str]] = (),
     ) -> budget_model.Budget:
-        r"""Creates a new budget. See
-        <a href="https://cloud.google.com/billing/quotas">Quotas
-        and limits</a> for more information on the limits of the
-        number of budgets you can create.
+        r"""Creates a new budget. See `Quotas and
+        limits <https://cloud.google.com/billing/quotas>`__ for more
+        information on the limits of the number of budgets you can
+        create.
 
 
         .. code-block::
@@ -236,7 +236,7 @@ def sample_create_budget():
                 # Make the request
                 response = client.create_budget(request=request)
 
-                # Handle response
+                # Handle the response
                 print(response)
 
         Args:
@@ -314,7 +314,7 @@ def sample_update_budget():
                 # Make the request
                 response = client.update_budget(request=request)
 
-                # Handle response
+                # Handle the response
                 print(response)
 
         Args:
@@ -406,7 +406,7 @@ def sample_get_budget():
                 # Make the request
                 response = client.get_budget(request=request)
 
-                # Handle response
+                # Handle the response
                 print(response)
 
         Args:
@@ -495,6 +495,8 @@ def sample_list_budgets():
 
                 # Make the request
                 page_result = client.list_budgets(request=request)
+
+                # Handle the response
                 for response in page_result:
                     print(response)
 
@@ -580,7 +582,7 @@ def sample_delete_budget():
                 )
 
                 # Make the request
-                response = client.delete_budget(request=request)
+                client.delete_budget(request=request)
 
         Args:
             request (Union[google.cloud.billing.budgets_v1beta1.types.DeleteBudgetRequest, dict]):

google/cloud/billing/budgets_v1beta1/services/budget_service/client.py

@@ -408,10 +408,10 @@ def create_budget(
         timeout: float = None,
         metadata: Sequence[Tuple[str, str]] = (),
     ) -> budget_model.Budget:
-        r"""Creates a new budget. See
-        <a href="https://cloud.google.com/billing/quotas">Quotas
-        and limits</a> for more information on the limits of the
-        number of budgets you can create.
+        r"""Creates a new budget. See `Quotas and
+        limits <https://cloud.google.com/billing/quotas>`__ for more
+        information on the limits of the number of budgets you can
+        create.
 
 
 
@@ -431,7 +431,7 @@ def sample_create_budget():
                 # Make the request
                 response = client.create_budget(request=request)
 
-                # Handle response
+                # Handle the response
                 print(response)
 
         Args:
@@ -511,7 +511,7 @@ def sample_update_budget():
                 # Make the request
                 response = client.update_budget(request=request)
 
-                # Handle response
+                # Handle the response
                 print(response)
 
         Args:
@@ -595,7 +595,7 @@ def sample_get_budget():
                 # Make the request
                 response = client.get_budget(request=request)
 
-                # Handle response
+                # Handle the response
                 print(response)
 
         Args:
@@ -676,6 +676,8 @@ def sample_list_budgets():
 
                 # Make the request
                 page_result = client.list_budgets(request=request)
+
+                # Handle the response
                 for response in page_result:
                     print(response)
 
@@ -753,7 +755,7 @@ def sample_delete_budget():
                 )
 
                 # Make the request
-                response = client.delete_budget(request=request)
+                client.delete_budget(request=request)
 
         Args:
             request (Union[google.cloud.billing.budgets_v1beta1.types.DeleteBudgetRequest, dict]):

google/cloud/billing/budgets_v1beta1/services/budget_service/transports/grpc.py

@@ -238,10 +238,10 @@ def create_budget(
     ) -> Callable[[budget_service.CreateBudgetRequest], budget_model.Budget]:
         r"""Return a callable for the create budget method over gRPC.
 
-        Creates a new budget. See
-        <a href="https://cloud.google.com/billing/quotas">Quotas
-        and limits</a> for more information on the limits of the
-        number of budgets you can create.
+        Creates a new budget. See `Quotas and
+        limits <https://cloud.google.com/billing/quotas>`__ for more
+        information on the limits of the number of budgets you can
+        create.
 
         Returns:
             Callable[[~.CreateBudgetRequest],

google/cloud/billing/budgets_v1beta1/services/budget_service/transports/grpc_asyncio.py

@@ -240,10 +240,10 @@ def create_budget(
     ) -> Callable[[budget_service.CreateBudgetRequest], Awaitable[budget_model.Budget]]:
         r"""Return a callable for the create budget method over gRPC.
 
-        Creates a new budget. See
-        <a href="https://cloud.google.com/billing/quotas">Quotas
-        and limits</a> for more information on the limits of the
-        number of budgets you can create.
+        Creates a new budget. See `Quotas and
+        limits <https://cloud.google.com/billing/quotas>`__ for more
+        information on the limits of the number of budgets you can
+        create.
 
         Returns:
             Callable[[~.CreateBudgetRequest],

google/cloud/billing/budgets_v1beta1/types/budget_model.py

@@ -72,10 +72,13 @@ class Budget(proto.Message):
         amount (google.cloud.billing.budgets_v1beta1.types.BudgetAmount):
             Required. Budgeted amount.
         threshold_rules (Sequence[google.cloud.billing.budgets_v1beta1.types.ThresholdRule]):
-            Optional. Rules that trigger alerts
-            (notifications of thresholds being crossed) when
-            spend exceeds the specified percentages of the
-            budget.
+            Optional. Rules that trigger alerts (notifications of
+            thresholds being crossed) when spend exceeds the specified
+            percentages of the budget.
+
+            Optional for ``pubsubTopic`` notifications.
+
+            Required if using email notifications.
         all_updates_rule (google.cloud.billing.budgets_v1beta1.types.AllUpdatesRule):
             Optional. Rules to apply to notifications
             sent based on budget spend and thresholds.
@@ -150,13 +153,25 @@ class LastPeriodAmount(proto.Message):
 
 
 class ThresholdRule(proto.Message):
-    r"""ThresholdRule contains a definition of a threshold which triggers an
-    alert (a notification of a threshold being crossed) to be sent when
-    spend goes above the specified amount. Alerts are automatically
-    e-mailed to users with the Billing Account Administrator role or the
-    Billing Account User role. The thresholds here have no effect on
-    notifications sent to anything configured under
-    ``Budget.all_updates_rule``.
+    r"""ThresholdRule contains the definition of a threshold. Threshold
+    rules define the triggering events used to generate a budget
+    notification email. When a threshold is crossed (spend exceeds the
+    specified percentages of the budget), budget alert emails are sent
+    to the email recipients you specify in the
+    `NotificationsRule <#notificationsrule>`__.
+
+    Threshold rules also affect the fields included in the `JSON data
+    object <https://cloud.google.com/billing/docs/how-to/budgets-programmatic-notifications#notification_format>`__
+    sent to a Pub/Sub topic.
+
+    Threshold rules are *required* if using email notifications.
+
+    Threshold rules are *optional* if only setting a ```pubsubTopic``
+    NotificationsRule <#NotificationsRule>`__, unless you want your JSON
+    data object to include data about the thresholds you set.
+
+    For more information, see `set budget threshold rules and
+    actions <https://cloud.google.com/billing/docs/how-to/budgets#budget-actions>`__.
 
     Attributes:
         threshold_percent (float):
@@ -282,13 +297,16 @@ class Filter(proto.Message):
             omitted, the report will include usage from the parent
             account and all subaccounts, if they exist.
         labels (Sequence[google.cloud.billing.budgets_v1beta1.types.Filter.LabelsEntry]):
-            Optional. A single label and value pair
-            specifying that usage from only this set of
-            labeled resources should be included in the
-            budget. Currently, multiple entries or multiple
-            values per entry are not allowed. If omitted,
-            the report will include all labeled and
-            unlabeled usage.
+            Optional. A single label and value pair specifying that
+            usage from only this set of labeled resources should be
+            included in the budget. If omitted, the report will include
+            all labeled and unlabeled usage.
+
+            An object containing a single ``"key": value`` pair.
+            Example: ``{ "name": "wrench" }``.
+
+            *Currently, multiple entries or multiple values per entry
+            are not allowed.*
         calendar_period (google.cloud.billing.budgets_v1beta1.types.CalendarPeriod):
             Optional. Specifies to track usage for
             recurring calendar period. For example, assume

samples/generated_samples/billingbudgets_generated_budgets_v1_budget_service_create_budget_async.py

@@ -39,7 +39,7 @@ async def sample_create_budget():
     # Make the request
     response = await client.create_budget(request=request)
 
-    # Handle response
+    # Handle the response
     print(response)
 
 # [END billingbudgets_generated_budgets_v1_BudgetService_CreateBudget_async]

samples/generated_samples/billingbudgets_generated_budgets_v1_budget_service_create_budget_sync.py

@@ -39,7 +39,7 @@ def sample_create_budget():
     # Make the request
     response = client.create_budget(request=request)
 
-    # Handle response
+    # Handle the response
     print(response)
 
 # [END billingbudgets_generated_budgets_v1_BudgetService_CreateBudget_sync]

samples/generated_samples/billingbudgets_generated_budgets_v1_budget_service_delete_budget_async.py

@@ -37,7 +37,7 @@ async def sample_delete_budget():
     )
 
     # Make the request
-    response = await client.delete_budget(request=request)
+    await client.delete_budget(request=request)
 
 
 # [END billingbudgets_generated_budgets_v1_BudgetService_DeleteBudget_async]

samples/generated_samples/billingbudgets_generated_budgets_v1_budget_service_delete_budget_sync.py

@@ -37,7 +37,7 @@ def sample_delete_budget():
     )
 
     # Make the request
-    response = client.delete_budget(request=request)
+    client.delete_budget(request=request)
 
 
 # [END billingbudgets_generated_budgets_v1_BudgetService_DeleteBudget_sync]

samples/generated_samples/billingbudgets_generated_budgets_v1_budget_service_get_budget_async.py

@@ -39,7 +39,7 @@ async def sample_get_budget():
     # Make the request
     response = await client.get_budget(request=request)
 
-    # Handle response
+    # Handle the response
     print(response)
 
 # [END billingbudgets_generated_budgets_v1_BudgetService_GetBudget_async]

samples/generated_samples/billingbudgets_generated_budgets_v1_budget_service_get_budget_sync.py

@@ -39,7 +39,7 @@ def sample_get_budget():
     # Make the request
     response = client.get_budget(request=request)
 
-    # Handle response
+    # Handle the response
     print(response)
 
 # [END billingbudgets_generated_budgets_v1_BudgetService_GetBudget_sync]

samples/generated_samples/billingbudgets_generated_budgets_v1_budget_service_list_budgets_async.py

@@ -38,6 +38,8 @@ async def sample_list_budgets():
 
     # Make the request
     page_result = client.list_budgets(request=request)
+
+    # Handle the response
     async for response in page_result:
         print(response)
 

samples/generated_samples/billingbudgets_generated_budgets_v1_budget_service_list_budgets_sync.py

@@ -38,6 +38,8 @@ def sample_list_budgets():
 
     # Make the request
     page_result = client.list_budgets(request=request)
+
+    # Handle the response
     for response in page_result:
         print(response)
 

samples/generated_samples/billingbudgets_generated_budgets_v1_budget_service_update_budget_async.py

@@ -38,7 +38,7 @@ async def sample_update_budget():
     # Make the request
     response = await client.update_budget(request=request)
 
-    # Handle response
+    # Handle the response
     print(response)
 
 # [END billingbudgets_generated_budgets_v1_BudgetService_UpdateBudget_async]