Improve table docs (#85)

Co-authored-by: Madhushree Ray <[email protected]>

.github/workflows/steampipe-anywhere.yml

@@ -0,0 +1,12 @@
+name: Release Steampipe Anywhere Components
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+
+jobs:
+  anywhere_publish_workflow:
+    uses: turbot/steampipe-workflows/.github/workflows/steampipe-anywhere.yml@main
+    secrets: inherit

README.md

@@ -30,6 +30,18 @@ from
   googledirectory_user;
 ```
 
+## Engines
+
+This plugin is available for the following engines:
+
+| Engine        | Description
+|---------------|------------------------------------------
+| [Steampipe](https://steampipe.io/docs) | The Steampipe CLI exposes APIs and services as a high-performance relational database, giving you the ability to write SQL-based queries to explore dynamic data. Mods extend Steampipe's capabilities with dashboards, reports, and controls built with simple HCL. The Steampipe CLI is a turnkey solution that includes its own Postgres database, plugin management, and mod support.
+| [Postgres FDW](https://steampipe.io/docs/steampipe_postgres/index) | Steampipe Postgres FDWs are native Postgres Foreign Data Wrappers that translate APIs to foreign tables. Unlike Steampipe CLI, which ships with its own Postgres server instance, the Steampipe Postgres FDWs can be installed in any supported Postgres database version.
+| [SQLite Extension](https://steampipe.io/docs//steampipe_sqlite/index) | Steampipe SQLite Extensions provide SQLite virtual tables that translate your queries into API calls, transparently fetching information from your API or service as you request it.
+| [Export](https://steampipe.io/docs/steampipe_export/index) | Steampipe Plugin Exporters provide a flexible mechanism for exporting information from cloud services and APIs. Each exporter is a stand-alone binary that allows you to extract data using Steampipe plugins without a database.
+| [Turbot Pipes](https://turbot.com/pipes/docs) | Turbot Pipes is the only intelligence, automation & security platform built specifically for DevOps. Pipes provide hosted Steampipe database instances, shared dashboards, snapshots, and more.
+
 ## Developing
 
 Prerequisites:
@@ -69,11 +81,17 @@ Further reading:
 - [Writing plugins](https://steampipe.io/docs/develop/writing-plugins)
 - [Writing your first table](https://steampipe.io/docs/develop/writing-your-first-table)
 
-## Contributing
+## Open Source & Contributing
+
+This repository is published under the [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) (source code) and [CC BY-NC-ND](https://creativecommons.org/licenses/by-nc-nd/2.0/) (docs) licenses. Please see our [code of conduct](https://github.com/turbot/.github/blob/main/CODE_OF_CONDUCT.md). We look forward to collaborating with you!
+
+[Steampipe](https://steampipe.io) is a product produced from this open source software, exclusively by [Turbot HQ, Inc](https://turbot.com). It is distributed under our commercial terms. Others are allowed to make their own distribution of the software, but cannot use any of the Turbot trademarks, cloud services, etc. You can learn more in our [Open Source FAQ](https://turbot.com/open-source).
+
+## Get Involved
 
-Please see the [contribution guidelines](https://github.com/turbot/steampipe/blob/main/CONTRIBUTING.md) and our [code of conduct](https://github.com/turbot/steampipe/blob/main/CODE_OF_CONDUCT.md). All contributions are subject to the [Apache 2.0 open source license](https://github.com/turbot/steampipe-plugin-googledirectory/blob/main/LICENSE).
+**[Join #steampipe on Slack →](https://turbot.com/community/join)**
 
-`help wanted` issues:
+Want to help but don't know where to start? Pick up one of the `help wanted` issues:
 
 - [Steampipe](https://github.com/turbot/steampipe/labels/help%20wanted)
 - [Google Directory Plugin](https://github.com/turbot/steampipe-plugin-googledirectory/labels/help%20wanted)

docs/index.md

@@ -8,13 +8,14 @@ short_name: "googledirectory"
 description: "Steampipe plugin for querying users, groups, org units and more from your Google Workspace directory."
 og_description: "Query Google Workspace directory with SQL! Open source CLI. No DB required."
 og_image: "/images/plugins/turbot/googledirectory-social-graphic.png"
+engines: ["steampipe", "sqlite", "postgres", "export"]
 ---
 
 # Google Directory + Steampipe
 
 A [Google Directory](https://developers.google.com/admin-sdk/directory) contains the users, groups, domains and other organizational features of a Google Workspace. [Google Workspace](https://workspace.google.com) is a collection of cloud computing, productivity and collaboration tools, software and products developed and marketed by Google.
 
-[Steampipe](https://steampipe.io) is an open source CLI to instantly query cloud APIs using SQL.
+[Steampipe](https://steampipe.io) is an open-source zero-ETL engine to instantly query cloud APIs using SQL.
 
 For example:
 
@@ -89,11 +90,6 @@ connection "googledirectory" {
 }
 ```
 
-## Get involved
-
-- Open source: https://github.com/turbot/steampipe-plugin-googledirectory
-- Community: [Join #steampipe on Slack →](https://turbot.com/community/join)
-
 ## Advanced configuration options
 
 ### Authenticate using OAuth client

docs/tables/googledirectory_domain.md

@@ -1,12 +1,31 @@
-# Table: googledirectory_domain
+---
+title: "Steampipe Table: googledirectory_domain - Query Google Directory Domains using SQL"
+description: "Allows users to query Google Directory Domains, providing detailed information about the domain and its associated settings and configurations."
+---
 
-Query information about domains defined in the Google Workspace directory.
+# Table: googledirectory_domain - Query Google Directory Domains using SQL
+
+Google Directory Domains is a resource within Google Workspace that allows you to manage your organization's domains. It provides a centralized way to set up and manage domains, including domain verification, alias management, and more. Google Directory Domains helps you stay informed about the status and settings of your domains and take appropriate actions when needed.
+
+## Table Usage Guide
+
+The `googledirectory_domain` table provides insights into domains within Google Workspace Directory. As a system administrator, explore domain-specific details through this table, including domain name, whether the domain is verified, and associated metadata. Utilize it to uncover information about domains, such as their verification status, and to manage domain aliases.
 
 ## Examples
 
 ### Basic info
+Explore which domains within your Google Directory are primary and when they were created. This can be beneficial for assessing domain configurations and understanding their establishment timeline.
+
+```sql+postgres
+select
+  domain_name,
+  creation_time,
+  is_primary
+from
+  googledirectory_domain;
+```
 
-```sql
+```sql+sqlite
 select
   domain_name,
   creation_time,
@@ -16,8 +35,9 @@ from
 ```
 
 ### List unverified domains
+Discover the segments that include unverified domains in your Google Directory. This can help you identify potential security risks and take necessary actions to verify these domains.
 
-```sql
+```sql+postgres
 select
   domain_name,
   creation_time,
@@ -27,3 +47,14 @@ from
 where
   not verified;
 ```
+
+```sql+sqlite
+select
+  domain_name,
+  creation_time,
+  verified
+from
+  googledirectory_domain
+where
+  not verified;
+```

docs/tables/googledirectory_domain_alias.md

@@ -1,12 +1,31 @@
-# Table: googledirectory_domain_alias
+---
+title: "Steampipe Table: googledirectory_domain_alias - Query Google Workspace Domain Aliases using SQL"
+description: "Allows users to query Domain Aliases in Google Workspace, specifically providing insights into the aliases associated with a Google Workspace domain."
+---
 
-Query information about domain aliases defined in the Google Workspace directory.
+# Table: googledirectory_domain_alias - Query Google Workspace Domain Aliases using SQL
+
+A Google Workspace Domain Alias is an alternative name for a Google Workspace domain, which allows users to log in to their accounts and services using different domain names. Domain aliases are particularly useful for organizations that operate under multiple brand names or have different domains for different departments. They are managed through the Google Admin console and can be used with all Google Workspace services.
+
+## Table Usage Guide
+
+The `googledirectory_domain_alias` table provides insights into domain aliases within Google Workspace. As a Google Workspace administrator, explore alias-specific details through this table, including the parent domain name, creation time, and whether the alias is verified. Utilize it to manage and monitor your organization's domain aliases, ensuring that all aliases are correctly set up and verified.
 
 ## Examples
 
 ### Basic info
+Explore which domain aliases in your Google Directory have been verified and when they were created. This can be used to maintain a secure and organized domain structure.
+
+```sql+postgres
+select
+  domain_alias_name,
+  creation_time,
+  verified
+from
+  googledirectory_domain_alias;
+```
 
-```sql
+```sql+sqlite
 select
   domain_alias_name,
   creation_time,
@@ -16,8 +35,20 @@ from
 ```
 
 ### List unverified domain aliases
+Discover the segments that consist of unverified domain aliases, enabling you to identify potential areas of risk and take appropriate action to verify them.
 
-```sql
+```sql+postgres
+select
+  domain_alias_name,
+  creation_time,
+  verified
+from
+  googledirectory_domain_alias
+where
+  not verified;
+```
+
+```sql+sqlite
 select
   domain_alias_name,
   creation_time,
@@ -29,8 +60,9 @@ where
 ```
 
 ### List domain aliases by parent domain
+Explore the different domain aliases associated with a specific parent domain. This can be useful for understanding the structure and organization of your domain aliases, as well as for verifying their creation times and statuses.
 
-```sql
+```sql+postgres
 select
   domain_alias_name,
   parent_domain_name,
@@ -41,3 +73,15 @@ from
 where
   parent_domain_name = 'domain.com';
 ```
+
+```sql+sqlite
+select
+  domain_alias_name,
+  parent_domain_name,
+  creation_time,
+  verified
+from
+  googledirectory_domain_alias
+where
+  parent_domain_name = 'domain.com';
+```

docs/tables/googledirectory_group.md

@@ -1,12 +1,32 @@
-# Table: googledirectory_group
+---
+title: "Steampipe Table: googledirectory_group - Query Google Directory Groups using SQL"
+description: "Allows users to query Google Directory Groups, specifically the group details and members, providing insights into the structure and membership of groups within the Google Workspace."
+---
 
-Query information about groups defined in the Google Workspace directory.
+# Table: googledirectory_group - Query Google Directory Groups using SQL
+
+Google Directory is a service within Google Workspace that allows you to manage, create, and view groups and their members. It provides a centralized way to set up and manage groups for various Google Workspace resources, including users, emails, and more. Google Directory helps you stay informed about the organization and membership of your Google Workspace resources.
+
+## Table Usage Guide
+
+The `googledirectory_group` table provides insights into groups within Google Workspace. As a system administrator, explore group-specific details through this table, including group names, emails, and associated metadata. Utilize it to uncover information about groups, such as those with certain members, the hierarchy of groups, and the verification of group properties.
 
 ## Examples
 
 ### Basic info
+Explore the basic information of Google Directory groups to gain insights into group names, IDs, associated emails, and creation details. This can be useful for managing and auditing group settings and memberships.
 
-```sql
+```sql+postgres
+select
+  name,
+  id,
+  email,
+  admin_created
+from
+  googledirectory_group;
+```
+
+```sql+sqlite
 select
   name,
   id,
@@ -17,8 +37,21 @@ from
 ```
 
 ### Get group by ID
+Discover the details of a specific group in your Google Directory by using its unique ID. This can be useful for gaining insights into group information such as its name, email, and administrative creation data.
 
-```sql
+```sql+postgres
+select
+  name,
+  id,
+  email,
+  admin_created
+from
+  googledirectory_group
+where
+  id = '02ce457p6conzyd';
+```
+
+```sql+sqlite
 select
   name,
   id,
@@ -31,8 +64,21 @@ where
 ```
 
 ### Get group by email
+Determine the areas in which a specific email address is associated with a group, allowing you to understand the context and scope of that group's administration. This can be particularly useful for managing and auditing access permissions in a large organization.
+
+```sql+postgres
+select
+  name,
+  id,
+  email,
+  admin_created
+from
+  googledirectory_group
+where
+  email = '[email protected]';
+```
 
-```sql
+```sql+sqlite
 select
   name,
   id,
@@ -45,8 +91,20 @@ where
 ```
 
 ### List top 5 groups by member count
+Explore the five most populated groups within your Google Directory. This could be useful for understanding which groups are most active or require the most resources.
 
-```sql
+```sql+postgres
+select
+  name,
+  direct_members_count
+from
+  googledirectory_group
+order by
+  direct_members_count desc
+limit 5;
+```
+
+```sql+sqlite
 select
   name,
   direct_members_count
@@ -58,8 +116,9 @@ limit 5;
 ```
 
 ### List all groups and their members
+Explore which members belong to specific groups within your Google Directory. This allows you to assess the composition of each group, aiding in tasks like group management and access control.
 
-```sql
+```sql+postgres
 select
   g.id as group_id,
   g.name as group_name,
@@ -74,9 +133,26 @@ order by
   m.email;
 ```
 
+```sql+sqlite
+select
+  g.id as group_id,
+  g.name as group_name,
+  m.email as member_email
+from
+  googledirectory_group as g
+join
+  googledirectory_group_member as m
+on
+  g.id = m.group_id
+order by
+  g.name,
+  m.email;
+```
+
 ### List groups using the [query filter](https://developers.google.com/admin-sdk/directory/v1/guides/search-groups)
+Explore which groups have been created by admins within the Google Directory, specifically focusing on those associated with an email containing 'steampipe'. This can be beneficial in understanding the extent of 'steampipe' usage across different groups.
 
-```sql
+```sql+postgres
 select
   name,
   id,
@@ -87,3 +163,15 @@ from
 where
   query = 'email:steampipe*';
 ```
+
+```sql+sqlite
+select
+  name,
+  id,
+  email,
+  admin_created
+from
+  googledirectory_group
+where
+  query = 'email:steampipe*';
+```