Improve table docs (#112)

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

@@ -82,6 +82,18 @@ from
 +-------------------------------+-----------+--------+-----------------------------+
 ```
 
+## 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:
@@ -121,11 +133,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-jira/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)
 - [Jira Plugin](https://github.com/turbot/steampipe-plugin-jira/labels/help%20wanted)

docs/index.md

@@ -8,14 +8,15 @@ short_name: "jira"
 description: "Steampipe plugin for querying sprints, issues, epics and more from Jira."
 og_description: "Query Jira with SQL! Open source CLI. No DB required."
 og_image: "/images/plugins/turbot/jira-social-graphic.png"
+engines: ["steampipe", "sqlite", "postgres", "export"]
 ---
 
 # Jira + Steampipe
 
 [Jira](https://www.atlassian.com/software/jira) provides on-demand cloud computing platforms and APIs to plan,
 track, and release great software.
 
-[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.
 
 List users in your Jira account:
 
@@ -104,7 +105,4 @@ export JIRA_TOKEN=8WqcdT0rvIZpCjtDqReF48B1
 export JIRA_PERSONAL_ACCESS_TOKEN="MDU0MDMx7cE25TQ3OujDfy/vkv/eeSXXoh/zXY1ex9cp"
 ```
 
-## Get involved
 
-- Open source: https://github.com/turbot/steampipe-plugin-jira
-- Community: [Join #steampipe on Slack →](https://turbot.com/community/join)

docs/tables/jira_advanced_setting.md

@@ -1,12 +1,32 @@
-# Table: jira_advanced_setting
+---
+title: "Steampipe Table: jira_advanced_setting - Query Jira Advanced Settings using SQL"
+description: "Allows users to query Advanced Settings in Jira, specifically the key and value pairs of settings, providing insights into system configurations and potential modifications."
+---
 
-Jira has a small number of commonly edited advanced configuration options, which are stored in the Jira database. These options can be accessed and edited from the Advanced Settings page. You must be a Jira System Administrator to do this.
+# Table: jira_advanced_setting - Query Jira Advanced Settings using SQL
+
+Jira Advanced Settings is a feature within Atlassian's Jira that allows you to customize and configure the system to suit your organization's needs. It provides a way to set up and manage key-value pairs for various settings, including index path, attachment size, and more. Jira Advanced Settings helps you stay informed about the current configurations and take appropriate actions when modifications are needed.
+
+## Table Usage Guide
+
+The `jira_advanced_setting` table provides insights into the advanced settings within Jira. As a system administrator, explore setting-specific details through this table, including the key and value pairs of each setting. Utilize it to uncover information about system configurations, such as attachment size, index path, and the possibility of potential modifications.
 
 ## Examples
 
 ### Basic info
+Explore the advanced settings in your Jira instance to understand their types and associated keys. This can be useful in assessing the current configuration and identifying areas for optimization or troubleshooting.
+
+```sql+postgres
+select
+  id,
+  name,
+  key,
+  type
+from
+  jira_advanced_setting;
+```
 
-```sql
+```sql+sqlite
 select
   id,
   name,
@@ -17,8 +37,9 @@ from
 ```
 
 ### list advanced settings that supports string type value
+Explore advanced settings within Jira that support string type values. This can be useful for configuring and customizing your Jira environment to best suit your needs.
 
-```sql
+```sql+postgres
 select
   id,
   name,
@@ -29,3 +50,15 @@ from
 where
   type = 'string';
 ```
+
+```sql+sqlite
+select
+  id,
+  name,
+  key,
+  type
+from
+  jira_advanced_setting
+where
+  type = 'string';
+```

docs/tables/jira_backlog_issue.md

@@ -1,12 +1,34 @@
-# Table: jira_backlog_issue
+---
+title: "Steampipe Table: jira_backlog_issue - Query Jira Backlog Issues using SQL"
+description: "Allows users to query Jira Backlog Issues, providing an overview of all issues currently in the backlog of a Jira project."
+---
 
-Issues are the building blocks of any Jira project. The backlog contains incomplete issues that are not assigned to any future or active sprint.
+# Table: jira_backlog_issue - Query Jira Backlog Issues using SQL
+
+Jira is a project management tool used for issue tracking, bug tracking, and agile project management. A Jira Backlog Issue refers to a task or a bug that has been identified but is not currently being worked on. These issues are stored in the backlog, a list of tasks or bugs that need to be addressed but have not yet been prioritized for action.
+
+## Table Usage Guide
+
+The `jira_backlog_issue` table provides insights into the backlog issues within a Jira project. As a project manager or a software developer, you can use this table to explore details of each issue, including its status, priority, and assignee. This can help you prioritize tasks, manage project workflows, and ensure timely resolution of bugs and tasks.
 
 ## Examples
 
 ### Basic info
+Explore which projects have been created, who initiated them, their current status, and a brief summary. This information can be useful to gain an overview of ongoing projects and their progress.
+
+```sql+postgres
+select
+  key,
+  project_key,
+  created,
+  creator_display_name,
+  status,
+  summary
+from
+  jira_backlog_issue;
+```
 
-```sql
+```sql+sqlite
 select
   key,
   project_key,
@@ -19,8 +41,25 @@ from
 ```
 
 ### List backlog issues for a specific project
+Explore the status and details of pending tasks within a specific project to manage workload and track progress effectively. This can help in prioritizing tasks and assigning them to the right team members.
+
+```sql+postgres
+select
+  id,
+  key,
+  project_key,
+  created,
+  creator_display_name,
+  assignee_display_name,
+  status,
+  summary
+from
+  jira_backlog_issue
+where
+  project_key = 'TEST1';
+```
 
-```sql
+```sql+sqlite
 select
   id,
   key,
@@ -37,8 +76,24 @@ where
 ```
 
 ### List backlog issues assigned to a specific user
+Explore which backlog issues are assigned to a specific user to manage and prioritize their workload efficiently. This is useful in tracking project progress and ensuring tasks are evenly distributed among team members.
+
+```sql+postgres
+select
+  id,
+  key,
+  summary,
+  project_key,
+  status,
+  assignee_display_name,
+  assignee_account_id
+from
+  jira_backlog_issue
+where
+  assignee_display_name = 'sayan';
+```
 
-```sql
+```sql+sqlite
 select
   id,
   key,
@@ -54,8 +109,9 @@ where
 ```
 
 ### List backlog issues due in 30 days
+Explore which backlog issues are due within the next 30 days to better manage your project timeline and delegate tasks effectively. This can assist in prioritizing work and ensuring that deadlines are met.
 
-```sql
+```sql+postgres
 select
   id,
   key,
@@ -71,3 +127,20 @@ where
   due_date > current_date
   and due_date <= (current_date + interval '30' day);
 ```
+
+```sql+sqlite
+select
+  id,
+  key,
+  summary,
+  project_key,
+  status,
+  assignee_display_name,
+  assignee_account_id,
+  due_date
+from
+  jira_backlog_issue
+where
+  due_date > date('now')
+  and due_date <= date('now', '+30 day');
+```

docs/tables/jira_board.md

@@ -1,19 +1,32 @@
-# Table: jira_board
+---
+title: "Steampipe Table: jira_board - Query Jira Boards using SQL"
+description: "Allows users to query Jira Boards, providing detailed insights into board configurations, types, and associated projects."
+---
 
-A **Board** displays issues from one or more projects, giving you a flexible way of viewing, managing, and reporting on work in progress.
-There are three types of boards in Jira Software:
+# Table: jira_board - Query Jira Boards using SQL
 
-- Team-managed board: For teams who are new to agile. Get your team up-and-running with this simplified board. The set-up is straight-forward and streamlined, delivering more power progressively as you need it.
+Jira Boards is a feature within Atlassian's Jira Software that allows teams to visualize their work. Boards can be customized to fit the unique workflow of any team, making it easier to manage tasks and projects. They provide a visual and interactive interface to track the progress of work.
 
-- Scrum board: For teams that plan their work in sprints. Includes a backlog.
+## Table Usage Guide
 
-- Kanban board: For teams that focus on managing and constraining their work-in-progress. Includes the option of a Kanban backlog.
+The `jira_board` table provides insights into Jira Boards within Atlassian's Jira Software. As a project manager or a team lead, you can explore board-specific details through this table, including board configurations, types, and associated projects. Utilize it to uncover information about boards, such as their associated projects, the types of boards, and their configurations.
 
 ## Examples
 
 ### Basic info
+Explore the types of boards in your Jira project and identify any associated filters. This can help in understanding the organization and management of tasks within your project.
 
-```sql
+```sql+postgres
+select
+  id,
+  name,
+  type,
+  filter_id
+from
+  jira_board;
+```
+
+```sql+sqlite
 select
   id,
   name,
@@ -24,8 +37,21 @@ from
 ```
 
 ### List all scrum boards
+Explore which project management boards are organized using the Scrum methodology. This can help you assess the prevalence and usage of this agile framework within your organization.
+
+```sql+postgres
+select
+  id,
+  name,
+  type,
+  filter_id
+from
+  jira_board
+where
+  type = 'scrum';
+```
 
-```sql
+```sql+sqlite
 select
   id,
   name,
@@ -38,8 +64,9 @@ where
 ```
 
 ### List sprints in a board
+Explore the various sprints associated with a specific board to manage project timelines effectively. This can help in tracking progress and identifying any bottlenecks in the project workflow.
 
-```sql
+```sql+postgres
 select
   s.board_id,
   b.name as board_name,
@@ -54,3 +81,20 @@ from
 where
   s.board_id = b.id;
 ```
+
+```sql+sqlite
+select
+  s.board_id,
+  b.name as board_name,
+  b.type as board_type,
+  s.id as sprint_id,
+  s.name as sprint_name,
+  start_date,
+  end_date
+from
+  jira_sprint as s
+join
+  jira_board as b
+on
+  s.board_id = b.id;
+```