docs(cockpit): revamp cockpit (#157)

Author: scaleway-bot

scaleway-async/scaleway_async/cockpit/v1beta1/api.py

@@ -77,8 +77,8 @@ class CockpitV1Beta1API(API):
     """
     Cockpit API.
 
-    This API allows to manage Cockpits.
     Cockpit API.
+    Cockpit's API allows you to activate your Cockpit on your Projects. Scaleway's Cockpit stores metrics and logs and provides a dedicated Grafana for dashboarding to visualize them.
     """
 
     async def activate_cockpit(
@@ -87,9 +87,9 @@ async def activate_cockpit(
         project_id: Optional[str] = None,
     ) -> Cockpit:
         """
-        Activate a cockpit.
-        Activate a cockpit associated with the given project ID.
-        :param project_id:
+        Activate a Cockpit.
+        Activate the Cockpit of the specified Project ID.
+        :param project_id: ID of the Project the Cockpit belongs to.
         :return: :class:`Cockpit <Cockpit>`
 
         Usage:
@@ -118,9 +118,9 @@ async def get_cockpit(
         project_id: Optional[str] = None,
     ) -> Cockpit:
         """
-        Get cockpit.
-        Get the cockpit associated with the given project ID.
-        :param project_id:
+        Get a Cockpit.
+        Retrieve the Cockpit of the specified Project ID.
+        :param project_id: ID of the Project the Cockpit belongs to.
         :return: :class:`Cockpit <Cockpit>`
 
         Usage:
@@ -148,7 +148,7 @@ async def wait_for_cockpit(
     ) -> Cockpit:
         """
         Waits for :class:`Cockpit <Cockpit>` to be in a final state.
-        :param project_id:
+        :param project_id: ID of the Project the Cockpit belongs to.
         :param options: The options for the waiter
         :return: :class:`Cockpit <Cockpit>`
 
@@ -181,14 +181,12 @@ async def get_cockpit_metrics(
         metric_name: Optional[str] = None,
     ) -> CockpitMetrics:
         """
-        Get cockpit metrics.
-        Get the cockpit metrics with the given project ID.
-        :param project_id: Project ID.
-        :param start_date: Start date.
-        Start date, if omited, query will be instant query and End Date will be used as query time.
-        :param end_date: End date.
-        End date, if omited set to now.
-        :param metric_name: Metric name.
+        Get Cockpit metrics.
+        Get metrics from your Cockpit with the specified Project ID.
+        :param project_id: ID of the Project the Cockpit belongs to.
+        :param start_date: Desired time range's start date for the metrics.
+        :param end_date: Desired time range's end date for the metrics.
+        :param metric_name: Name of the metric requested.
         :return: :class:`CockpitMetrics <CockpitMetrics>`
 
         Usage:
@@ -217,9 +215,9 @@ async def deactivate_cockpit(
         project_id: Optional[str] = None,
     ) -> Cockpit:
         """
-        Deactivate a cockpit.
-        Deactivate a cockpit associated with the given project ID.
-        :param project_id:
+        Deactivate a Cockpit.
+        Deactivate the Cockpit of the specified Project ID.
+        :param project_id: ID of the Project the Cockpit belongs to.
         :return: :class:`Cockpit <Cockpit>`
 
         Usage:
@@ -248,9 +246,9 @@ async def reset_cockpit_grafana(
         project_id: Optional[str] = None,
     ) -> Cockpit:
         """
-        Reset Grafana.
-        Reset the Grafana of your cockpit associated with the given project ID.
-        :param project_id:
+        Reset a Grafana.
+        Reset your Cockpit's Grafana associated with the specified Project ID.
+        :param project_id: ID of the Project the Cockpit belongs to.
         :return: :class:`Cockpit <Cockpit>`
 
         Usage:
@@ -282,10 +280,10 @@ async def create_token(
     ) -> Token:
         """
         Create a token.
-        Create a token associated with the given project ID.
-        :param project_id:
-        :param name:
-        :param scopes:
+        Create a token associated with the specified Project ID.
+        :param project_id: ID of the Project.
+        :param name: Name of the token.
+        :param scopes: Token's permissions.
         :return: :class:`Token <Token>`
 
         Usage:
@@ -320,11 +318,11 @@ async def list_tokens(
     ) -> ListTokensResponse:
         """
         List tokens.
-        List tokens associated with the given project ID.
-        :param page:
-        :param page_size:
+        Get a list of tokens associated with the specified Project ID.
+        :param page: Page number.
+        :param page_size: Page size.
         :param order_by:
-        :param project_id:
+        :param project_id: ID of the Project.
         :return: :class:`ListTokensResponse <ListTokensResponse>`
 
         Usage:
@@ -357,11 +355,11 @@ async def list_tokens_all(
     ) -> List[Token]:
         """
         List tokens.
-        List tokens associated with the given project ID.
-        :param page:
-        :param page_size:
+        Get a list of tokens associated with the specified Project ID.
+        :param page: Page number.
+        :param page_size: Page size.
         :param order_by:
-        :param project_id:
+        :param project_id: ID of the Project.
         :return: :class:`List[ListTokensResponse] <List[ListTokensResponse]>`
 
         Usage:
@@ -388,9 +386,9 @@ async def get_token(
         token_id: str,
     ) -> Token:
         """
-        Get token.
-        Get the token associated with the given ID.
-        :param token_id:
+        Get a token.
+        Retrieve the token associated with the specified token ID.
+        :param token_id: ID of the token.
         :return: :class:`Token <Token>`
 
         Usage:
@@ -415,9 +413,9 @@ async def delete_token(
         token_id: str,
     ) -> Optional[None]:
         """
-        Delete token.
-        Delete the token associated with the given ID.
-        :param token_id:
+        Delete a token.
+        Delete the token associated with the specified token ID.
+        :param token_id: ID of the token.
 
         Usage:
         ::
@@ -442,9 +440,9 @@ async def create_contact_point(
         contact_point: Optional[ContactPoint] = None,
     ) -> ContactPoint:
         """
-        Create an alert contact point.
-        Create an alert contact point for the default receiver.
-        :param project_id: Project ID.
+        Create a contact point.
+        Create a contact point to receive alerts for the default receiver.
+        :param project_id: ID of the Project in which to create the contact point.
         :param contact_point: Contact point to create.
         :return: :class:`ContactPoint <ContactPoint>`
 
@@ -477,11 +475,11 @@ async def list_contact_points(
         project_id: Optional[str] = None,
     ) -> ListContactPointsResponse:
         """
-        List alert contact points.
-        List alert contact points associated with the given cockpit ID.
+        List contact points.
+        Get a list of contact points for the Cockpit associated with the specified Project ID.
         :param page: Page number.
         :param page_size: Page size.
-        :param project_id: Project ID.
+        :param project_id: ID of the Project from which to list the contact points.
         :return: :class:`ListContactPointsResponse <ListContactPointsResponse>`
 
         Usage:
@@ -511,11 +509,11 @@ async def list_contact_points_all(
         project_id: Optional[str] = None,
     ) -> List[ContactPoint]:
         """
-        List alert contact points.
-        List alert contact points associated with the given cockpit ID.
+        List contact points.
+        Get a list of contact points for the Cockpit associated with the specified Project ID.
         :param page: Page number.
         :param page_size: Page size.
-        :param project_id: Project ID.
+        :param project_id: ID of the Project from which to list the contact points.
         :return: :class:`List[ListContactPointsResponse] <List[ListContactPointsResponse]>`
 
         Usage:
@@ -543,8 +541,8 @@ async def delete_contact_point(
     ) -> Optional[None]:
         """
         Delete an alert contact point.
-        Delete an alert contact point for the default receiver.
-        :param project_id:
+        Delete a contact point for the default receiver.
+        :param project_id: ID of the Project.
         :param contact_point: Contact point to delete.
 
         Usage:
@@ -575,7 +573,8 @@ async def enable_managed_alerts(
     ) -> Optional[None]:
         """
         Enable managed alerts.
-        :param project_id:
+        Enable the sending of managed alerts for the specified Project's Cockpit.
+        :param project_id: ID of the Project.
 
         Usage:
         ::
@@ -604,7 +603,8 @@ async def disable_managed_alerts(
     ) -> Optional[None]:
         """
         Disable managed alerts.
-        :param project_id:
+        Disable the sending of managed alerts for the specified Project's Cockpit.
+        :param project_id: ID of the Project.
 
         Usage:
         ::
@@ -633,7 +633,7 @@ async def trigger_test_alert(
     ) -> Optional[None]:
         """
         Trigger a test alert.
-        Trigger a test alert to all receivers.
+        Trigger a test alert to all of the Cockpit's receivers.
         :param project_id:
 
         Usage:
@@ -664,11 +664,11 @@ async def create_grafana_user(
         project_id: Optional[str] = None,
     ) -> GrafanaUser:
         """
-        Create a grafana user.
-        Create a grafana user for your grafana instance.
-        :param project_id:
-        :param login:
-        :param role:
+        Create a Grafana user.
+        Create a Grafana user for your Cockpit's Grafana instance. Make sure you save the automatically-generated password and the Grafana user ID.
+        :param project_id: ID of the Project.
+        :param login: Username of the Grafana user.
+        :param role: Role assigned to the Grafana user.
         :return: :class:`GrafanaUser <GrafanaUser>`
 
         Usage:
@@ -705,12 +705,12 @@ async def list_grafana_users(
         project_id: Optional[str] = None,
     ) -> ListGrafanaUsersResponse:
         """
-        List grafana users.
-        List grafana users who are able to connect to your grafana instance.
-        :param page:
-        :param page_size:
+        List Grafana users.
+        Get a list of Grafana users who are able to connect to the Cockpit's Grafana instance.
+        :param page: Page number.
+        :param page_size: Page size.
         :param order_by:
-        :param project_id:
+        :param project_id: ID of the Project.
         :return: :class:`ListGrafanaUsersResponse <ListGrafanaUsersResponse>`
 
         Usage:
@@ -742,12 +742,12 @@ async def list_grafana_users_all(
         project_id: Optional[str] = None,
     ) -> List[GrafanaUser]:
         """
-        List grafana users.
-        List grafana users who are able to connect to your grafana instance.
-        :param page:
-        :param page_size:
+        List Grafana users.
+        Get a list of Grafana users who are able to connect to the Cockpit's Grafana instance.
+        :param page: Page number.
+        :param page_size: Page size.
         :param order_by:
-        :param project_id:
+        :param project_id: ID of the Project.
         :return: :class:`List[ListGrafanaUsersResponse] <List[ListGrafanaUsersResponse]>`
 
         Usage:
@@ -775,10 +775,10 @@ async def delete_grafana_user(
         project_id: Optional[str] = None,
     ) -> Optional[None]:
         """
-        Delete a grafana user.
-        Delete a grafana user from your grafana instance.
-        :param grafana_user_id:
-        :param project_id:
+        Delete a Grafana user.
+        Delete a Grafana user from a Grafana instance, specified by the Cockpit's Project ID and the Grafana user ID.
+        :param grafana_user_id: ID of the Grafana user.
+        :param project_id: ID of the Project.
 
         Usage:
         ::
@@ -810,10 +810,10 @@ async def reset_grafana_user_password(
         project_id: Optional[str] = None,
     ) -> GrafanaUser:
         """
-        Reset Grafana user password.
-        Reset the Grafana user password from your grafana instance.
-        :param grafana_user_id:
-        :param project_id:
+        Reset a Grafana user's password.
+        Reset a Grafana user's password specified by the Cockpit's Project ID and the Grafana user ID.
+        :param grafana_user_id: ID of the Grafana user.
+        :param project_id: ID of the Project.
         :return: :class:`GrafanaUser <GrafanaUser>`
 
         Usage:
@@ -847,10 +847,10 @@ async def list_plans(
         order_by: ListPlansRequestOrderBy = ListPlansRequestOrderBy.NAME_ASC,
     ) -> ListPlansResponse:
         """
-        List plans.
-        List all pricing plans.
-        :param page:
-        :param page_size:
+        List pricing plans.
+        Get a list of all pricing plans available.
+        :param page: Page number.
+        :param page_size: Page size.
         :param order_by:
         :return: :class:`ListPlansResponse <ListPlansResponse>`
 
@@ -881,10 +881,10 @@ async def list_plans_all(
         order_by: Optional[ListPlansRequestOrderBy] = None,
     ) -> List[Plan]:
         """
-        List plans.
-        List all pricing plans.
-        :param page:
-        :param page_size:
+        List pricing plans.
+        Get a list of all pricing plans available.
+        :param page: Page number.
+        :param page_size: Page size.
         :param order_by:
         :return: :class:`List[ListPlansResponse] <List[ListPlansResponse]>`
 
@@ -913,9 +913,9 @@ async def select_plan(
     ) -> SelectPlanResponse:
         """
         Select pricing plan.
-        Select the wanted pricing plan.
-        :param project_id:
-        :param plan_id:
+        Select your chosen pricing plan for your Cockpit, specifying the Cockpit's Project ID and the pricing plan's ID in the request.
+        :param project_id: ID of the Project.
+        :param plan_id: ID of the pricing plan.
         :return: :class:`SelectPlanResponse <SelectPlanResponse>`
 
         Usage: