Merge pull request #198 from Mara3l/master

DP-2330 Data Sources documentation Reviewed-by: Jan Kadlec https://github.com/hkad98
gooddata · Jan 13, 2023 · 40fb15b · 40fb15b
2 parents a4f9b55 + de7894c
commit 40fb15b
Show file tree

Hide file tree

Showing 27 changed files with 624 additions and 37 deletions.
diff --git a/.gitignore b/.gitignore
@@ -6,3 +6,4 @@
 test_clients.py
 gooddata-sdk/tests/catalog/store
 .DS_Store
+.vscode
diff --git a/gooddata-sdk/docs/hugo/docs/assets/scss/_styles_project.scss b/gooddata-sdk/docs/hugo/docs/assets/scss/_styles_project.scss
@@ -20,6 +20,8 @@
 @import "homepage";
 @import "tables";
 @import "content-select";
+@import "parameters-block";
+@import "parameter";
 
 #print {
   display: none; // Hide print functionality for now

diff --git a/gooddata-sdk/docs/hugo/docs/assets/scss/parameter.scss b/gooddata-sdk/docs/hugo/docs/assets/scss/parameter.scss
@@ -0,0 +1,3 @@
+.gd-docs-parameter {
+    text-align: left;
+}
diff --git a/gooddata-sdk/docs/hugo/docs/assets/scss/parameters-block.scss b/gooddata-sdk/docs/hugo/docs/assets/scss/parameters-block.scss
@@ -0,0 +1,4 @@
+.gd-docs-parameters-block {
+    width: 100%;
+    text-align: left;
+}
diff --git a/gooddata-sdk/docs/hugo/docs/content/en/docs/_index.md b/gooddata-sdk/docs/hugo/docs/content/en/docs/_index.md
@@ -48,14 +48,14 @@ Integrate GoodData analytics into your continuous delivery practices by, for exa
 ```python
 # Reads visualizations from workspace
 insights = sdk.insights.get_insights("123")
-
+
 # Iterate through visualizations and check if they are valid
 for insight in insights:
     try:
         sdk.tables.for_insight("123", insight)
     except Exception:
         print(f"Visualization {insight.title} is broken.")
-
+
 ```
 
 #### Create data pipelines

diff --git a/gooddata-sdk/docs/hugo/docs/content/en/docs/data/data-source/_index.md b/gooddata-sdk/docs/hugo/docs/content/en/docs/data/data-source/_index.md
@@ -42,7 +42,7 @@ See [Connect Data](https://www.gooddata.com/developers/cloud-native/doc/cloud/co
 Since there are multiple data source types, here are examples, how to initialize each of them:
 
 ### Postgres
-
+
 ```python
 CatalogDataSourcePostgres(
     id=data_source_id,
@@ -58,9 +58,9 @@ CatalogDataSourcePostgres(
     ),
 )
 ```
-
+
 ### Redshift
-
+
 ```python
 CatalogDataSourceRedshift(
     id=data_source_id,
@@ -77,7 +77,7 @@ CatalogDataSourceRedshift(
 )
 ```
 ### Snowflake
-
+
 ```python
 CatalogDataSourceSnowflake(
     id=data_source_id,
@@ -95,7 +95,7 @@ CatalogDataSourceSnowflake(
 )
 ```
 ### Vertica
-
+
 ```python
 CatalogDataSourceVertica(
     id=data_source_id,
@@ -111,9 +111,9 @@ CatalogDataSourceVertica(
     ),
 )
 ```
-
+
 ### BigQuery
-
+
 ```python
 CatalogDataSourceBigQuery(
     id=data_source_id,
@@ -126,7 +126,7 @@ CatalogDataSourceBigQuery(
 )
 ```
 ### Greenplum
-
+
 ```python
 CatalogDataSourceGreenplum(
     id=data_source_id,

diff --git a/...docs/hugo/docs/content/en/docs/data/data-source/create_or_update_data_source.md b/...docs/hugo/docs/content/en/docs/data/data-source/create_or_update_data_source.md
@@ -9,7 +9,18 @@ superheading: "catalog_data_source."
 
 ``create_or_update_data_source(data_source: CatalogDataSource)``
 
-Create or update data source.
+Pushes the Data Source to the GoodData environment. Automatically decides, whether to create or update.
+
+{{% parameters-block  title="Parameters"%}}
+
+{{< parameter p_name="data_source" p_type="CatalogDataSource" >}}
+Catalog Data Source object
+{{< /parameter >}}
+
+{{% /parameters-block %}}
+
+{{% parameters-block title="Returns" None="yes"%}}
+{{% /parameters-block %}}
 
 ### Example
 

diff --git a/gooddata-sdk/docs/hugo/docs/content/en/docs/data/data-source/delete_data_source.md b/gooddata-sdk/docs/hugo/docs/content/en/docs/data/data-source/delete_data_source.md
@@ -11,6 +11,17 @@ superheading: "catalog_data_source."
 
 Delete data source using data source id.
 
+{{% parameters-block  title="Parameters"%}}
+
+{{< parameter p_name="data_source_id" p_type="string" >}}
+Data Source identification string e.g. "demo"
+{{< /parameter >}}
+
+{{< /parameters-block >}}
+
+{{% parameters-block title="Returns" None="yes"%}}
+{{% /parameters-block %}}
+
 ### Example
 
 ```python

diff --git a/...a-sdk/docs/hugo/docs/content/en/docs/data/data-source/generate_logical_model.md b/...a-sdk/docs/hugo/docs/content/en/docs/data/data-source/generate_logical_model.md
@@ -9,10 +9,28 @@ superheading: "catalog_data_source."
 
 ``generate_logical_model(data_source_id: str, generate_ldm_request: CatalogGenerateLdmRequest)``
 
-Returns *CatalogDeclarativeModel*.
-
 Generate logical data model for a data source.
 
+{{% parameters-block  title="Parameters"%}}
+
+{{< parameter p_name="data_source_id" p_type="str" >}}
+Data Source identification string e.g. "demo"
+{{< /parameter >}}
+
+{{< parameter p_name="generate_ldm_request" p_type="Optional[CatalogGenerateLdmRequest]" >}}
+LDM options. Defaults to CatalogGenerateLdmRequest(separator="__", wdf_prefix="wdf")
+{{< /parameter >}}
+
+{{% /parameters-block %}}
+
+{{% parameters-block title="Returns"%}}
+
+{{< parameter p_type="CatalogDeclarativeModel" >}}
+Logical Data Model object.
+{{< /parameter >}}
+
+{{% /parameters-block %}}
+
 ## Example
 
 ```Python

diff --git a/gooddata-sdk/docs/hugo/docs/content/en/docs/data/data-source/get_data_source.md b/gooddata-sdk/docs/hugo/docs/content/en/docs/data/data-source/get_data_source.md
@@ -9,10 +9,23 @@ superheading: "catalog_data_source."
 
 ``get_data_source(data_source_id: str)``
 
-Returns *CatalogDataSource*.
-
 Retrieve data source using data source id.
 
+{{% parameters-block  title="Parameters"%}}
+
+{{< parameter p_name="data_source_id" p_type="str" >}}
+Data Source identification string e.g. "demo"
+{{< /parameter >}}
+
+{{% /parameters-block %}}
+
+{{% parameters-block title="Returns"%}}
+{{< parameter p_type="CatalogDataSource" >}}
+Data Source Object
+{{< /parameter >}}
+
+{{% /parameters-block %}}
+
 ## Example
 
 ```python

diff --git a/...docs/hugo/docs/content/en/docs/data/data-source/get_declarative_data_sources.md b/...docs/hugo/docs/content/en/docs/data/data-source/get_declarative_data_sources.md
@@ -13,6 +13,14 @@ Returns *CatalogDeclarativeDataSources*.
 
 Retrieve all data sources, including their related physical data model.
 
+{{% parameters-block title="Parameters" None="yes" %}}
+{{% /parameters-block %}}
+{{% parameters-block title="Returns"%}}
+{{< parameter p_type="CatalogDeclarativeDataSources" >}}
+Data Source Object, including physical data model.
+{{< /parameter >}}
+{{% /parameters-block %}}
+
 ## Example
 
 ```python

diff --git a/...-sdk/docs/hugo/docs/content/en/docs/data/data-source/list_data_source_tables.md b/...-sdk/docs/hugo/docs/content/en/docs/data/data-source/list_data_source_tables.md
@@ -9,9 +9,22 @@ superheading: "catalog_data_source."
 
 ``list_data_source_tables(data_source_id: str)``
 
-Returns *List[CatalogDataSourceTable]*
+Lists all the data source tables for a given data source.
 
-Lists all tables for a data source specified by id.
+{{% parameters-block  title="Parameters"%}}
+
+{{< parameter p_name="data_source_id" p_type="str" >}}
+Data Source identification string e.g. "demo"
+{{< /parameter >}}
+
+{{% /parameters-block %}}
+
+{{% parameters-block title="Returns"%}}
+{{< parameter p_type="List[CatalogDataSourceTable]" >}}
+List of Data Source Table objects
+{{< /parameter >}}
+
+{{% /parameters-block %}}
 
 ## Example
 

diff --git a/gooddata-sdk/docs/hugo/docs/content/en/docs/data/data-source/list_data_sources.md b/gooddata-sdk/docs/hugo/docs/content/en/docs/data/data-source/list_data_sources.md
@@ -9,10 +9,20 @@ superheading: "catalog_data_source."
 
 ``list_data_sources()``
 
-Returns *List[CatalogDataSource]*.
-
 Lists all data sources.
 
+
+{{% parameters-block title="Parameters" None="yes"%}}
+{{% /parameters-block %}}
+
+{{% parameters-block title="Returns"%}}
+
+{{% parameter p_type="List[CatalogDataSource]" %}}
+List of all Data Sources in the whole organization.
+{{% /parameter %}}
+
+{{% /parameters-block %}}
+
 ```Python
 # List all data sources
 data_sources = sdk.catalog_data_sources.list_data_sources()

diff --git a/.../docs/content/en/docs/data/data-source/load_and_put_declarative_data_sources.md b/.../docs/content/en/docs/data/data-source/load_and_put_declarative_data_sources.md
@@ -11,6 +11,23 @@ superheading: "catalog_data_source."
 
 This method combines [load_declarative_data_sources](../load_and_put_declarative_data_sources) and [put_declarative_data_sources](../put_declarative_data_sources) methods to load and set layouts stored using [store_declarative_data_sources](../store_declarative_data_sources).
 
+{{% parameters-block  title="Parameters"%}}
+
+{{< parameter p_name="layout_root_path" p_type="CatalogDeclarativeDataSources" >}}
+Path to the root of the layout directory. Defaults to Path.cwd().
+{{< /parameter >}}
+{{< parameter p_name="credentials_path" p_type="Optional[Path]" >}}
+Path to the credentials. Defaults to Path.cwd().
+{{< /parameter >}}
+{{< parameter p_name="test_data_sources" p_type="Optional[Bool]" >}}
+If True, the connection of data sources is tested. Defaults to False.
+{{< /parameter >}}
+
+{{% /parameters-block %}}
+
+{{% parameters-block title="Returns" None="yes"%}}
+{{% /parameters-block %}}
+
 ## Example
 
 The load and put can be done two ways.

diff --git a/...ocs/hugo/docs/content/en/docs/data/data-source/load_declarative_data_sources.md b/...ocs/hugo/docs/content/en/docs/data/data-source/load_declarative_data_sources.md
@@ -13,6 +13,24 @@ Returns *CatalogDeclarativeDataSources*.
 
 Load declarative data sources layout, which was stored using [store_declarative_data_sources](../store_declarative_data_sources).
 
+{{% parameters-block  title="Parameters"%}}
+
+{{< parameter p_name="declarative_data_sources" p_type="CatalogDeclarativeDataSources" >}}
+ Declarative Data Sources object
+{{< /parameter >}}
+{{< parameter p_name="layout_root_path" p_type="Optional[Path]" >}}
+Path to the root of the layout directory. Defaults to Path.cwd().
+{{< /parameter >}}
+
+{{% /parameters-block %}}
+
+{{% parameters-block title="Returns"%}}
+
+{{< parameter p_type="CatalogDeclarativeDataSources" >}}
+Declarative Data Sources object
+{{< /parameter >}}
+{{% /parameters-block %}}
+
 ## Example
 
 ```python

diff --git a/...docs/hugo/docs/content/en/docs/data/data-source/patch_data_source_attributes.md b/...docs/hugo/docs/content/en/docs/data/data-source/patch_data_source_attributes.md
@@ -9,7 +9,23 @@ superheading: "catalog_data_source."
 
 ``patch_data_source_attributes(data_source_id: str, attributes: dict)``
 
-Allows you to apply changes to the given data source.
+Applies changes to the specified data source.
+
+{{% parameters-block  title="Parameters"%}}
+
+{{< parameter p_name="data_source_id" p_type="string" >}}
+Data Source identification string e.g. "demo"
+{{< /parameter >}}
+
+{{< parameter p_name="attributes" p_type="dictionary" >}}
+A dictionary containing attributes of the data source to be changed.
+{{< /parameter >}}
+
+{{% /parameters-block %}}
+
+
+{{% parameters-block title="Returns" None="yes"%}}
+{{% /parameters-block %}}
 
 ## Example
 

diff --git a/...docs/hugo/docs/content/en/docs/data/data-source/put_declarative_data_sources.md b/...docs/hugo/docs/content/en/docs/data/data-source/put_declarative_data_sources.md
@@ -11,6 +11,24 @@ superheading: "catalog_data_source."
 
 Set all data sources, including their related physical data model.
 
+{{% parameters-block title="Parameters"%}}
+
+{{< parameter p_name="declarative_data_sources" p_type="CatalogDeclarativeDataSources" >}}
+Declarative Data Source object. Can be retrieved by get_declarative_data_sources.
+{{< /parameter >}}
+
+{{< parameter p_name="credentials_path" p_type="Optional[Path]" >}}
+Path to the Credentials. Optional, defaults to None.
+{{< /parameter >}}
+
+{{< parameter p_name="test_data_sources" p_type="Optional[bool]" >}}
+If True, the connection of data sources is tested. Defaults to False.
+{{< /parameter >}}
+
+{{% /parameters-block %}}
+
+{{% parameters-block title="Returns" None="yes"%}}
+{{% /parameters-block %}}
 ## Example
 
 ```python

diff --git a/...docs/hugo/docs/content/en/docs/data/data-source/register_upload_notification.md b/...docs/hugo/docs/content/en/docs/data/data-source/register_upload_notification.md
@@ -11,6 +11,17 @@ superheading: "catalog_data_source."
 
 Invalidate cache of your computed reports to force your analytics to be recomputed.
 
+{{% parameters-block  title="Parameters"%}}
+
+{{< parameter p_name="data_source_id" p_type="string" >}}
+Data Source identification string. e.g. "demo"
+{{< /parameter >}}
+
+{{% /parameters-block %}}
+
+{{% parameters-block title="Returns" None="yes"%}}
+{{% /parameters-block %}}
+
 ## Example
 
 ```Python