WIP - [docs] Query type docs

docs/sources/_index.md

@@ -2,6 +2,25 @@
 title: GitHub data source plugin for Grafana
 menuTitle: GitHub data source
 description: The GitHub data source lets you visualize GitHub data in Grafana dashboards.
+hero:
+  title: Github data source plugin for Grafana
+  level: 1
+  width: 110
+  image: https://raw.githubusercontent.com/grafana/github-datasource/refs/heads/main/src/img/github.svg
+  height: 110
+  description: The Github data source plugin allows you to query and visualize data from Github.
+query_types:
+  title_class: pt-0 lh-1
+  items:
+    - title: Repositories
+      description: List the github repositories for an organization
+      href: /docs/grafana-github-datasource/latest/query/repositories/
+    - title: Issues
+      description: List the issues created for a github repo
+      href: /docs/grafana-github-datasource/latest/query/issues/
+    - title: Pull Requests
+      description: List the pull requests created for a github repo
+      href: /docs/grafana-github-datasource/latest/query/pull-requests/
 keywords:
   - data source
   - github
@@ -15,6 +34,12 @@ labels:
 weight: 10
 ---
 
+<!-- markdownlint-configure-file { "MD013": false, "MD033": false, "MD025": false, "MD034": false } -->
+
+{{< docs/hero-simple key="hero" >}}
+
+<hr style="margin-bottom:30px"/>
+
 # GitHub data source plugin for Grafana
 
 The GitHub data source plugin for Grafana lets you to query the GitHub API in Grafana so you can visualize your GitHub repositories and projects.
@@ -25,16 +50,19 @@ Watch this video to learn more about setting up the Grafana GitHub data source p
 
 ## Query types
 
-The plugin supports the following query types:
+Grafana Github datasource plugin allows you query various data from github. To know more about supported query types and details, refer the [Query page](/docs/grafana-github-datasource/latest/query/)
+
+{{< card-grid key="query_types" type="simple" >}}
+
+### Other query types
+
+The plugin also supports the following query types:
 
 - Commits
-- Issues
 - Contributors
 - Tags
 - Releases
-- Pull requests
 - Labels
-- Repositories
 - Milestones
 - Packages
 - Vulnerabilities

docs/sources/annotations/_index.md

@@ -12,7 +12,7 @@ labels:
     - oss
     - enterprise
     - cloud
-weight: 400
+weight: 500
 ---
 
 # Create annotations with GitHub data source plugin for Grafana

docs/sources/query/_index.md

@@ -0,0 +1,60 @@
+---
+title: 'Query'
+menuTitle: Query
+description: Query
+hero:
+  title: Github data source plugin for Grafana
+  level: 1
+  width: 110
+  image: https://raw.githubusercontent.com/grafana/github-datasource/refs/heads/main/src/img/github.svg
+  height: 110
+  description: The Github data source plugin allows you to query and visualize data from Github.
+keywords:
+  - github
+  - ci
+  - cd
+query_types:
+  title_class: pt-0 lh-1
+  items:
+    - title: Repositories
+      description: List the github repositories for an organization
+      href: /docs/grafana-github-datasource/latest/query/repositories/
+    - title: Issues
+      description: List the issues created for a github repo
+      href: /docs/grafana-github-datasource/latest/query/issues/
+    - title: Pull Requests
+      description: List the pull requests created for a github repo
+      href: /docs/grafana-github-datasource/latest/query/pull-requests/
+labels:
+  products:
+    - oss
+weight: 300
+---
+
+<!-- markdownlint-configure-file { "MD013": false, "MD033": false, "MD025": false, "MD034": false } -->
+
+{{< docs/hero-simple key="hero" >}}
+
+<hr style="margin-bottom:30px"/>
+
+## 🎯 Supported query types
+
+{{< card-grid key="query_types" type="simple" >}}
+
+### Other query types
+
+The plugin also supports the following query types:
+
+- Commits
+- Contributors
+- Tags
+- Releases
+- Labels
+- Milestones
+- Packages
+- Vulnerabilities
+- Projects
+- Stargazers
+- Workflows
+- Workflow usage
+- Workflow runs

docs/sources/query/issues.md

@@ -0,0 +1,74 @@
+---
+title: Issues
+menuTitle: Issues
+description: Issues
+hero:
+  title: List issues
+  level: 1
+  width: 110
+  image: https://raw.githubusercontent.com/grafana/github-datasource/refs/heads/main/src/img/github.svg
+  height: 110
+  description: List issues created in a github repo
+keywords:
+  - github
+  - ci
+  - cd
+labels:
+  products:
+    - oss
+weight: 302
+---
+
+<!-- markdownlint-configure-file { "MD013": false, "MD033": false} -->
+
+{{< docs/hero-simple key="hero" >}}
+
+<hr style="margin-bottom:30px"/>
+
+Query type **Issues** allows you to list the issues created in a GitHub repository.
+
+## Query Parameters
+
+| Field      | Description                                                             | Example   |
+| ---------- | ----------------------------------------------------------------------- | --------- |
+| Query Type | Specify the query type as **Issues**                                    |           |
+| Owner      | GitHub user id / organization id                                        | grafana   |
+| Repository | Name of the repository                                                  | grafana   |
+| Options    | **(Optional)**. Additional options such as search query and time field. | See below |
+
+### Options
+
+| Field          | Description                                                                                                                                                                                                                                                                   | Example                  |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| **Query**      | _(Optional)_ Search string to filter issues. You can use the same syntax as GitHub's search field.                                                                                                                                                                            | `is:OPEN label:type/bug` |
+| **Time Field** | _(Optional)_ Field to use for time filtering (`created`=0, `closed`=1, `updated`=2). If nothing selected, defaults to `created at` and the results will be filtered automatically based on the date. <br/>**Tip**: Grafana's dashboard time range used for these time filters | 0                        |
+
+### Query Schema
+
+```json
+{
+  "queryType": "Issues",
+  "owner": "grafana",
+  "repository": "grafana",
+  "options": {
+    "query": "is:open label:bug",
+    "timeField": "created"
+  }
+}
+```
+
+#### Downstream Query
+
+Under the hood, Grafana uses the following GraphQL query to list the issues:
+
+```graphql
+TBD
+```
+
+## Result field
+
+Refer to the [GitHub GraphQL documentation](https://docs.github.com/en/graphql/overview/explorer) for details about all the result fields presented in the GraphQL query.
+
+## Known Limitations
+
+- The GitHub plugin paginates over the GraphQL query with a 100 items limit per request. If the repository has a large number of issues, the result might be slower. Use appropriate filters (query, timeField) to improve query performance.

docs/sources/query/pull-requests.md

@@ -0,0 +1,28 @@
+---
+title: Pull Requests
+menuTitle: Pull Requests
+description: Pull Request
+hero:
+  title: List pull requests
+  level: 1
+  width: 110
+  image: https://raw.githubusercontent.com/grafana/github-datasource/refs/heads/main/src/img/github.svg
+  height: 110
+  description: List pull requests created in a github repo
+keywords:
+  - github
+  - ci
+  - cd
+labels:
+  products:
+    - oss
+weight: 302
+---
+
+<!-- markdownlint-configure-file { "MD013": false, "MD033": false} -->
+
+{{< docs/hero-simple key="hero" >}}
+
+<hr style="margin-bottom:30px"/>
+
+TBD

docs/sources/query/repositories.md

@@ -0,0 +1,82 @@
+---
+title: Repositories
+menuTitle: Repositories
+description: Repositories
+hero:
+  title: List github repositories
+  level: 1
+  width: 110
+  image: https://raw.githubusercontent.com/grafana/github-datasource/refs/heads/main/src/img/github.svg
+  height: 110
+  description: List github repositories for a github organization / user
+keywords:
+  - github
+  - ci
+  - cd
+labels:
+  products:
+    - oss
+weight: 301
+---
+
+<!-- markdownlint-configure-file { "MD013": false, "MD033": false} -->
+
+{{< docs/hero-simple key="hero" >}}
+
+<hr style="margin-bottom:30px"/>
+
+Query type **Repositories** allow you to list the repositories available for a github user/organization
+
+## Query Parameters
+
+| Field      | Description                                                                                                                                                               | Example                                                                |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| Query Type | Specify the query type as **Repository**                                                                                                                                  |                                                                        |
+| Owner      | Github user id / organization id                                                                                                                                          | grafana                                                                |
+| Repository | **(Optional)**. Search field. Typically full name of the repository or partial search string.<br/>**Tip**: You can use the same syntax you use in github.com search field | `datasource` / `grafana-infinity-datasource` / `datasources -lang:go`. |
+
+### Query Schema
+
+```json
+{
+  "queryType": "Repositories",
+  "owner": "grafana",
+  "repository": "datasource"
+}
+```
+
+#### Downstream Query
+
+Under the hood, grafana uses the following GraphQL query to list the repositories
+
+```graphql
+{
+  search(query: "org:grafana datasource", type: REPOSITORY, first: 100) {
+    nodes {
+      ... on Repository {
+        name
+        owner {
+          login
+        }
+        nameWithOwner
+        url
+        forks {
+          totalCount
+        }
+        isFork
+        isMirror
+        isPrivate
+        createdAt
+      }
+    }
+  }
+}
+```
+
+## Result field
+
+Refer the [Github GraphQL documentation](https://docs.github.com/en/graphql/overview/explorer) for the details about all the result fields presented in the GraphQL query.
+
+## Known Limitations
+
+- Github plugin does pagination over the graphQL query with 100 pages limit on each request. If the owner/user have more number of repositories, then there are potential chances that the result might be slower. Use appropriate search filer in the repository field to increase the query performance.

docs/sources/variables-and-macros/_index.md

@@ -12,7 +12,7 @@ labels:
     - oss
     - enterprise
     - cloud
-weight: 200
+weight: 400
 ---
 
 # Use GitHub data source variables and macros in Grafana

docs/sources/variables-and-macros/macros.md

@@ -12,7 +12,7 @@ labels:
     - oss
     - enterprise
     - cloud
-weight: 202
+weight: 402
 ---
 
 # Use macros with GitHub data source plugin for Grafana

docs/sources/variables-and-macros/variables.md

@@ -12,7 +12,7 @@ labels:
     - oss
     - enterprise
     - cloud
-weight: 201
+weight: 401
 ---
 
 # Create variable with GitHub data source plugin for Grafana

docs/variables.mk

@@ -1 +1 @@
-PROJECTS := github-datasource
+PROJECTS := grafana-github-datasource