fix: convert RST-style docstrings to Google style for docs generation

hkad98 · hkad98 · commit 9a00fc2fd6bf · 2026-03-16T09:57:19.000+01:00
The docs json_builder.py script expects Google-style docstrings but several
functions used RST-style (:param/:return:), had missing summary lines before
Args sections, or had improperly indented continuation lines — all causing
"Invalid docstring" warnings during docs generation.

jira: TRIVIAL
risk: low
diff --git a/packages/gooddata-pandas/src/gooddata_pandas/data_access.py b/packages/gooddata-pandas/src/gooddata_pandas/data_access.py
@@ -230,7 +230,7 @@ def build_execution_definition(self, filter_by: Union[Filter, list[Filter]] | No
 
         Args:
             filter_by (Optional[Union[Filter, list[Filter]]]): A filter or a list of filters to be applied to the
-            execution definition. If it's not provided or None, then the current filter configuration is used.
+                execution definition. If it's not provided or None, then the current filter configuration is used.
 
         Returns:
             ExecutionDefinition: An ExecutionDefinition instance containing attributes, metrics, filters,
diff --git a/packages/gooddata-pandas/src/gooddata_pandas/dataframe.py b/packages/gooddata-pandas/src/gooddata_pandas/dataframe.py
@@ -60,7 +60,8 @@ class DataFrameFactory:
     """
 
     def __init__(self, sdk: GoodDataSdk, workspace_id: str) -> None:
-        """
+        """Create a new DataFrameFactory.
+
         Args:
             sdk (GoodDataSdk): GoodData SDK instance.
             workspace_id (str): Workspace identifier.
diff --git a/packages/gooddata-pandas/src/gooddata_pandas/series.py b/packages/gooddata-pandas/src/gooddata_pandas/series.py
@@ -38,37 +38,26 @@ def indexed(
         of the index labels. The elements of the index labels will be used to construct simple or hierarchical index.
 
         Args:
-            index_by (IndexDef): label to index by; specify either:
-
-            - string with id: ``some_label_id``,
-            - object identifier: ``ObjId(id='some_label_id', type='label')``,
-            - string representation of object identifier: ``label/some_label_id``
-            - or an Attribute object used in the compute model: ``Attribute(local_id=..., label='some_label_id')``
-            - dict containing mapping of index name to label to use for indexing (in one of the ways listed above)
-
-            data_by (Union[SimpleMetric, str, ObjId, Attribute]): label, fact or metric to that will provide data
-              (metric values or label elements); specify either:
-
-            - object identifier: ``ObjId(id='some_id', type='<type>')`` - where type is either ``label``, ``fact``
-              or ``metric``
-            - string representation of object identifier: ``<type>/some_id`` - where type is either ``label``, ``fact``
-              or ``metric``
-            - Attribute object used in the compute model: ``Attribute(local_id=..., label='some_label_id')``
-            - SimpleMetric object used in the compute model: ``SimpleMetric(local_id=..., item=..., aggregation=...)``
-
-            filter_by (Optional[Union[Filter, list[Filter]]]): optionally specify filter to apply during computation on
-            the server, reference to filtering column can be one of:
-
-            - string reference to index key
-            - object identifier in string form
-            - object identifier: ``ObjId(id='some_label_id', type='<type>')``
-            - Attribute or Metric depending on type of filter
-
+            index_by (IndexDef): label to index by; specify either
+                a string with id (``some_label_id``),
+                an object identifier (``ObjId(id='some_label_id', type='label')``),
+                a string representation of object identifier (``label/some_label_id``),
+                an Attribute object used in the compute model
+                (``Attribute(local_id=..., label='some_label_id')``),
+                or a dict containing mapping of index name to label to use for indexing.
+            data_by (Union[SimpleMetric, str, ObjId, Attribute]): label, fact or metric that will provide data
+                (metric values or label elements); specify either an object identifier
+                (``ObjId(id='some_id', type='<type>')``), a string representation
+                (``<type>/some_id``), an Attribute object, or a SimpleMetric object.
+            filter_by (Optional[Union[Filter, list[Filter]]]): optionally specify filter to apply during
+                computation on the server, reference to filtering column can be a string reference to
+                index key, object identifier in string form,
+                ``ObjId(id='some_label_id', type='<type>')``,
+                or Attribute/Metric depending on type of filter.
             on_execution_submitted (Optional[Callable[[Execution], None]]): Callback to call when the execution was
                 submitted to the backend.
-
-            is_cancellable (bool, optional): Whether the execution should be cancelled when the connection is interrupted.
-
+            is_cancellable (bool, optional): Whether the execution should be cancelled when the connection
+                is interrupted.
             result_page_len (Optional[int]): Optional page size for result pagination.
                 Defaults to 1000. Larger values can improve performance for large result sets.
 
diff --git a/packages/gooddata-sdk/src/gooddata_sdk/catalog/workspace/service.py b/packages/gooddata-sdk/src/gooddata_sdk/catalog/workspace/service.py
@@ -191,13 +191,17 @@ def list_workspace_settings(self, workspace_id: str) -> list[CatalogWorkspaceSet
         return [CatalogWorkspaceSetting.from_api(ws) for ws in workspace_settings]
 
     def resolve_all_workspace_settings(self, workspace_id: str) -> dict:
-        """
-        Resolves values for all settings in a workspace by current user, workspace, organization, or default settings
-        and return them as a dictionary. Proper parsing is up to the caller.
+        """Resolve values for all settings in a workspace.
+
+        Resolves by current user, workspace, organization, or default settings
+        and returns them as a dictionary. Proper parsing is up to the caller.
         TODO: long-term we should return a proper entity object.
 
-        :param workspace_id: Workspace ID
-        :return: Dict of settings
+        Args:
+            workspace_id: Workspace ID
+
+        Returns:
+            Dict of settings
         """
         # note: in case some settings were recently added and the API client was not regenerated it can fail on
         #       invalid value when validating allowed types on the client side before request is sent to the server
@@ -211,14 +215,18 @@ def resolve_all_workspace_settings(self, workspace_id: str) -> dict:
         return {setting["type"]: setting for setting in resolved_workspace_settings}
 
     def resolve_workspace_settings(self, workspace_id: str, settings: list) -> dict:
-        """
-        Resolves values for given settings in a workspace by current user, workspace, organization, or default settings
-        and return them as a dictionary. Proper parsing is up to the caller.
+        """Resolve values for given settings in a workspace.
+
+        Resolves by current user, workspace, organization, or default settings
+        and returns them as a dictionary. Proper parsing is up to the caller.
         TODO: long-term we should return a proper entity object.
 
-        :param workspace_id: Workspace ID
-        :param settings: List of settings to resolve
-        :return: Dict of settings
+        Args:
+            workspace_id: Workspace ID
+            settings: List of settings to resolve
+
+        Returns:
+            Dict of settings
         """
         resolved_workspace_settings = [
             setting.to_dict()
diff --git a/packages/gooddata-sdk/src/gooddata_sdk/compute/compute_to_sdk_converter.py b/packages/gooddata-sdk/src/gooddata_sdk/compute/compute_to_sdk_converter.py
@@ -43,10 +43,13 @@ class ComputeToSdkConverter:
 
     @staticmethod
     def convert_attribute(attribute_dict: dict[str, Any]) -> Attribute:
-        """
-        Converts attribute dictionary to the SDK Compute model.
-        :param attribute_dict: the attribute dictionary to convert
-        :return: the converted attribute
+        """Convert attribute dictionary to the SDK Compute model.
+
+        Args:
+            attribute_dict: the attribute dictionary to convert
+
+        Returns:
+            the converted attribute
         """
         return Attribute(
             local_id=attribute_dict["localIdentifier"],
@@ -56,10 +59,13 @@ def convert_attribute(attribute_dict: dict[str, Any]) -> Attribute:
 
     @staticmethod
     def convert_filter(filter_dict: dict[str, Any]) -> Filter:
-        """
-        Converts filter dictionary to the SDK Compute model.
-        :param filter_dict: the filter dictionary to convert
-        :return: the converted filter
+        """Convert filter dictionary to the SDK Compute model.
+
+        Args:
+            filter_dict: the filter dictionary to convert
+
+        Returns:
+            the converted filter
         """
         if "positiveAttributeFilter" in filter_dict:
             f = filter_dict["positiveAttributeFilter"]
@@ -186,10 +192,13 @@ def convert_filter(filter_dict: dict[str, Any]) -> Filter:
 
     @staticmethod
     def convert_metric(metric_dict: dict[str, Any]) -> Metric:
-        """
-        Converts metric dictionary to the SDK Compute model.
-        :param metric_dict: the metric dictionary to convert
-        :return: the converted metric
+        """Convert metric dictionary to the SDK Compute model.
+
+        Args:
+            metric_dict: the metric dictionary to convert
+
+        Returns:
+            the converted metric
         """
         definition = metric_dict["definition"]
         local_id = metric_dict["localIdentifier"]
diff --git a/packages/gooddata-sdk/src/gooddata_sdk/compute/model/base.py b/packages/gooddata-sdk/src/gooddata_sdk/compute/model/base.py
@@ -87,11 +87,14 @@ def as_api_model(self) -> OpenApiModel:
         raise NotImplementedError()
 
     def description(self, labels: dict[str, str], format_locale: str | None = None) -> str:
-        """
-        Description of the filter as it's visible for customer in UI.
+        """Description of the filter as it's visible for customer in UI.
+
+        Args:
+            labels: Dict of labels in a form of ``id: label``. Measures and attributes are expected to be here.
+            format_locale: Locale ICU format to use for dates formatting in the description
+                (ie. "en-US" or "cs-CZ")
 
-        :param labels: Dict of labels in a form of `id: label`. Measures and attributes are expected to be here.
-        :param format_locale: Locale ICU format to use for dates formatting in the description (ie. "en-US" or "cs-CZ")
-        :return: Filter's human-readable description
+        Returns:
+            Filter's human-readable description
         """
         raise NotImplementedError()
diff --git a/packages/gooddata-sdk/src/gooddata_sdk/type_converter.py b/packages/gooddata-sdk/src/gooddata_sdk/type_converter.py
@@ -119,10 +119,10 @@ class TypeConverterRegistry:
     """
 
     def __init__(self, type_name: str):
-        """
-        Initialize instance with type for which instance is going to be responsible
+        """Initialize instance with type for which instance is going to be responsible.
 
-        :param type_name: type name
+        Args:
+            type_name: type name
         """
         self._type_name = type_name
         self._converters: dict[str, Converter] = {}
@@ -160,10 +160,10 @@ def _register_with_sub_type(self, converter: Converter, sub_type: str) -> None:
         self._converters[sub_type] = converter
 
     def _register_default(self, converter: Converter) -> None:
-        """
-        Register default converter instance for the type. Default type can be registered only once.
+        """Register default converter instance for the type. Default type can be registered only once.
 
-        :param converter: converter instance
+        Args:
+            converter: converter instance
         """
         if self._default_converter:
             reg_converter_type = self._default_converter.__class__.__name__
