Merge pull request #131 from andriichumak/features/fix-autodoc-format…

…ting Fix docstring annotations for better rendering online Reviewed-by: Jan Soubusta https://github.com/jaceksan
gooddata · Aug 8, 2022 · 42e166f · 42e166f
2 parents b496cf0 + 80a5682
commit 42e166f
Show file tree

Hide file tree

Showing 12 changed files with 134 additions and 111 deletions.
diff --git a/gooddata-fdw/gooddata_fdw/column_utils.py b/gooddata-fdw/gooddata_fdw/column_utils.py
@@ -28,6 +28,7 @@ def table_col_as_computable(col: ColumnDefinition) -> Union[Attribute, Metric]:
 def column_data_type_for(attribute: Optional[CatalogAttribute]) -> str:
     """
     Determine what postgres type should be used for `attribute`.
+
     :param attribute: catalog attribute instance
     """
     if not attribute:

diff --git a/gooddata-pandas/gooddata_pandas/dataframe.py b/gooddata-pandas/gooddata_pandas/dataframe.py
@@ -23,14 +23,14 @@ class DataFrameFactory:
 
     There are several methods in place that should provide for convenient construction of data frames:
 
-        - indexed() - calculate measure values sliced by one or more labels, indexed by those labels
-        - not_indexed() - calculate measure values sliced by one or more labels, but not indexed by those labels,
-            label values will be part of the DataFrame and will be in the same row as the measure values calculated
-            for them
-        - for_items() - calculate measure values for a one or more items which may be labels or measures. Depending
-            what items you specify, this method will create DataFrame with or without index
-        - for_insight() - calculate DataFrame for insight created by GoodData.CN Analytical Designer. Depending
-            on what items are in the insight, this method will create DataFrame with or without index.
+    - ``indexed()`` - calculate measure values sliced by one or more labels, indexed by those labels
+    - ``not_indexed()`` - calculate measure values sliced by one or more labels, but not indexed by those labels,
+      label values will be part of the DataFrame and will be in the same row as the measure values calculated
+      for them
+    - ``for_items()`` - calculate measure values for a one or more items which may be labels or measures. Depending
+      what items you specify, this method will create DataFrame with or without index
+    - ``for_insight()`` - calculate DataFrame for insight created by GoodData.CN Analytical Designer. Depending
+      on what items are in the insight, this method will create DataFrame with or without index.
 
     Note that all of these methods have additional levels of convenience and flexibility so their purpose is not
     limited to just what is listed above.
@@ -53,26 +53,31 @@ def indexed(
         Note that depending on composition of the labels, the DataFrame's index may or may not be unique.
 
         :param index_by: one or more labels to index by; specify either:
+
          - string with reference to columns key - only attribute can be referenced
-         - string with id: 'some_label_id',
-         - string representation of object identifier: 'label/some_label_id'
-         - object identifier: ObjId(id='some_label_id', type='label'),
-         - or an Attribute object used in the compute model: Attribute(local_id=..., label='some_label_id'),
+         - string with id: ``some_label_id``,
+         - string representation of object identifier: ``label/some_label_id``
+         - object identifier: ``ObjId(id='some_label_id', type='label')``,
+         - 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 - specified in one of the ways list above
 
         :param columns: dict mapping column name to its definition; column may be specified as:
-         - 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')
+
+         - 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')``
          - subclass of Measure object used in the compute model: SimpleMeasure, PopDateMeasure, PopDatasetMeasure,
-         ArithmeticMeasure
+           ArithmeticMeasure
+
         :param filter_by: optional filters to apply during computation on the server, reference to filtering column
-            can be one of:
-            - string reference to column key or index key
-            - object identifier in string form
-            - object identifier: ObjId(id='some_label_id', type='<type>')
-            - Attribute or Metric depending on type of filter
+         can be one of:
+
+         - string reference to column key or index key
+         - object identifier in string form
+         - object identifier: ``ObjId(id='some_label_id', type='<type>')``
+         - Attribute or Metric depending on type of filter
 
         :return: pandas dataframe instance
         """
@@ -98,18 +103,22 @@ def not_indexed(
         to aggregate values of metric columns.
 
         :param columns: dict mapping column name to its definition; column may be specified as:
-         - 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')
+
+         - 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')``
          - subclass of Measure object used in the compute model: SimpleMeasure, PopDateMeasure, PopDatasetMeasure,
-         ArithmeticMeasure
+           ArithmeticMeasure
+
         :param filter_by: optionally specify filters to apply during computation on the server, reference to filtering
-            column can be one of:
-            - string reference to column key
-            - object identifier in string form
-            - object identifier: ObjId(id='some_label_id', type='<type>')
-            - Attribute or Metric depending on type of filter
+         column can be one of:
+
+         - string reference to column key
+         - object identifier in string form
+         - object identifier: ``ObjId(id='some_label_id', type='<type>')``
+         - Attribute or Metric depending on type of filter
 
         :return: pandas dataframe instance
         """
@@ -125,30 +134,33 @@ def for_items(
         Creates a data frame for a named items. This is a convenience method that will create DataFrame with or
         without index based on the context of the items that you pass.
 
-            - If items contain labels and measures, then DataFrame with index will be created. If there is more than
-               one label among the items, then hierarchical index will be created.
+        - If items contain labels and measures, then DataFrame with index will be created. If there is more than
+          one label among the items, then hierarchical index will be created.
 
-               You can turn this behavior using 'auto_index' parameter.
+          You can turn this behavior using 'auto_index' parameter.
 
-            - Otherwise DataFrame without index will be created and will contain column per item.
+        - Otherwise DataFrame without index will be created and will contain column per item.
 
         You may also optionally specify filters to apply during the computation on the server.
 
         :param items: dict mapping item name to its definition; item may be specified as:
-             - 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')
-             - subclass of Measure object used in the compute model: SimpleMeasure, PopDateMeasure, PopDatasetMeasure,
-             ArithmeticMeasure
+
+         - 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')``
+         - subclass of Measure object used in the compute model: SimpleMeasure, PopDateMeasure, PopDatasetMeasure,
+           ArithmeticMeasure
+
         :param filter_by: optionally specify filters to apply during computation on the server, reference to filtering
-            column can be one of:
-            - string reference to item key
-            - object identifier in string form
-            - object identifier: ObjId(id='some_label_id', type='<type>')
-            - Attribute or Metric depending on type of filter
-        :param auto_index: optionally force creation of DataFrame without index even if the contents of items make it
-            eligible for indexing
+         column can be one of:
+
+         - string reference to item key
+         - object identifier in string form
+         - object identifier: ``ObjId(id='some_label_id', type='<type>')``
+         - Attribute or Metric depending on type of filter
+
         :return: pandas dataframe instance
         """
         resolved_attr_cols: dict[str, LabelItemDef] = dict()
@@ -186,20 +198,21 @@ def for_insight(self, insight_id: str, auto_index: bool = True) -> pandas.DataFr
         This method will create DataFrame with or without index - depending on the contents of the insight. The
         rules are as follows:
 
-            - if the insight contains both attributes and measures, it will be mapped to a DataFrame with index
-               - if there are multiple attributes, hieararchical index (pandas.MultiIndex) will be used
-               - otherwise a normal index will be used (pandas.Index)
-               - you can use the option 'auto_index' argument to disable this logic and force no indexing
+        - if the insight contains both attributes and measures, it will be mapped to a DataFrame with index
+
+          - if there are multiple attributes, hieararchical index (pandas.MultiIndex) will be used
+          - otherwise a normal index will be used (pandas.Index)
+          - you can use the option 'auto_index' argument to disable this logic and force no indexing
 
-            - if the insight contains either only attributes or only measures, then DataFrame will not be indexed
-              and all attribute or measures values will be used as data.
+        - if the insight contains either only attributes or only measures, then DataFrame will not be indexed
+          and all attribute or measures values will be used as data.
 
-           Note that if the insight consists of single measure only, the resulting data frame is guaranteed to have
-           single 'row' of data with one column per measure.
+        Note that if the insight consists of single measure only, the resulting data frame is guaranteed to have
+        single 'row' of data with one column per measure.
 
         :param insight_id: insight identifier
         :param auto_index: optionally force creation of DataFrame without index even if the data in the insight is
-            eligible for indexing
+         eligible for indexing
 
         :return: pandas dataframe instance
         """

diff --git a/gooddata-pandas/gooddata_pandas/series.py b/gooddata-pandas/gooddata_pandas/series.py
@@ -27,29 +27,32 @@ def indexed(
 
         :param index_by: 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')
+         - 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 - specified in one of the ways list above
 
         :param data_by: 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=...)
+         - 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=...)``
 
         :param filter_by: 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
+         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
+
+        :return: pandas series instance
 
-        :return pandas series instance
         """
         data, index = compute_and_extract(
             self._sdk,
@@ -77,29 +80,31 @@ def not_indexed(
 
         :param data_by: label, fact or metric to get data from; 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=...)
+         - 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=...)``
 
         :param granularity: optionally specify label to slice the metric 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')
+         - 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')``
          - list containing multiple labels to slice the metric by - specified in one of the ways list above
          - dict containing mapping of index name to label to use for indexing - specified in one of the ways list above;
            this option is available so that you can easily switch from indexed factory method to this one if needed
 
         :param filter_by: optionally specify filter to apply during computation on the server, reference to filtering
-            column can be one of:
-            - object identifier in string form
-            - object identifier: ObjId(id='some_label_id', type='<type>')
-            - Attribute or Metric depending on type of filter
+         column can be one of:
+
+         - object identifier in string form
+         - object identifier: ``ObjId(id='some_label_id', type='<type>')``
+         - Attribute or Metric depending on type of filter
 
-        :return pandas series instance
+        :return: pandas series instance
         """
 
         if isinstance(granularity, list):

diff --git a/gooddata-sdk/gooddata_sdk/catalog/workspace/model_container.py b/gooddata-sdk/gooddata_sdk/catalog/workspace/model_container.py
@@ -55,7 +55,7 @@ def get_metric(self, metric_id: Union[str, ObjId]) -> Union[CatalogMetric, None]
 
         :return: instance of CatalogMetric or None if no such metric in catalog
 
-        :rtype CatalogMetric
+        :rtype: CatalogMetric
         """
         if isinstance(metric_id, ObjId):
             obj_id_str = str(metric_id)
@@ -68,14 +68,14 @@ def get_metric(self, metric_id: Union[str, ObjId]) -> Union[CatalogMetric, None]
 
     def get_dataset(self, dataset_id: Union[str, ObjId]) -> Union[CatalogDataset, None]:
         """
-        Gets dataset by id. The id can be either an instance of ObjId or string containing serialized ObjId
-        ('dataset/some.dataset.id') or contain just the id part ('some.dataset.id').
+        Gets dataset by id. The id can be either an instance of ObjId or string containing serialized ``ObjId
+        ('dataset/some.dataset.id')`` or contain just the id part (``some.dataset.id``).
 
         :param dataset_id: fully qualified dataset entity id (type/id) or just the identifier of dataset entity
 
         :return: instance of CatalogDataset or None if no such dataset in catalog
 
-        :rtype CatalogDataset
+        :rtype: CatalogDataset
         """
         if isinstance(dataset_id, ObjId):
             obj_id_str = str(dataset_id)
@@ -106,11 +106,11 @@ def catalog_with_valid_objects(self, ctx: ValidObjectsInputType) -> CatalogWorks
         the filtered catalog will contain only those entities that can be safely added on top of that existing context.
 
         :param ctx: existing context. you can specify context in one of the following ways:
-            - single item or list of items from the execution model
-            - single item or list of items from catalog model; catalog fact, label or metric may be added
-            - the entire execution definition that is used to compute analytics
 
-        :return:
+         - single item or list of items from the execution model
+         - single item or list of items from catalog model; catalog fact, label or metric may be added
+         - the entire execution definition that is used to compute analytics
+
         """
         valid_objects = self._valid_objects(ctx)