docs: add query docs for github

[sympatheticmoose]

This PR adds detailed documentation for the query types supported by the github data source

It introduces a summary table of all available types as well as details on:

• query parameters
• sample queries
• response data

TODO:

• review by @sympatheticmoose

Notes for reviewers:

• Packages response is best effort based on packages.go - I was unable to query this successfully
• Unsure on the value column for vulnerabilities, again took a guess.

Potential follow ups:

• Add screenshots for sample responses
• We could optionally extend this to cover specific permission requirements on query
• Similarly I wonder if we should indicate whether a query respects datetime picker in some form or not
• I got a little lazy with table formatting, this could be improved, but never sure on best approach when column values are on the lengthy side

[sympatheticmoose]

@lwandz13 please take a look at this PR in combination with the draft alternative here #466

Beyond content review, we would appreciate your insights on recommended format/layout - i.e. should we have query types in a single page or broken out into individual pages under a query section?

[lwandz13]

@lwandz13 please take a look at this PR in combination with the draft alternative here #466

Beyond content review, we would appreciate your insights on recommended format/layout - i.e. should we have query types in a single page or broken out into individual pages under a query section?

I'd keep this all on one page. Users can click the link to jump to the section(s) that apply to their use case.

l I'm looking for heading and title guidance in our Writer's Toolkit and don't see any. I'll refer you to Google's style guide (which is what ours is based on) for heading and title guidance. https://developers.google.com/style/headings#markdown

I did a quick review, I'll do a more comprehensive one in the next day or two.

[itsgareth]

LGTM, but maybe you also want to wait for a review from the docs team

[itsgareth]

due to this weight change the following weights should also be updated:
/variables-and-macros > variables.md from 201 to 301,
/variables-and-macros > macros.md from 202 to 302

[sympatheticmoose]

Weird in a way... I thought the weights were relative within a directory? i.e. this will only affect the order from within the variables and macros subfolder.

I can make the change for consistency, but imo these should be 100 and 200 respectively

[itsgareth]

should we move both notes to the bottom?

Suggested change

	{{< admonition type="note" >}}
	This query returns a maximum of 200 results.
	{{< /admonition >}}
	{{< admonition type="note" >}}
	GitHub Projects allow for customization of default fields and custom fields to be added,
	therefore the response can vary significantly between projects."
	{{< /admonition >}}

personally think its looks cleaner/easier to read with this change, WDYT?

[sympatheticmoose]

Hmm, the note on the customization only applies for the response where a project number is specified, whereas the query limit is generic...

How about moving query limit notes consistently higher up - i.e. before query options?

[lwandz13]

If using headings like ##### Sample queries you should skip a line. You can also just use Sample queries instead of using a heading.

https://grafana.com/docs/writers-toolkit/write/markdown-guide/#heading-donts

[sympatheticmoose]

@lwandz13 thank you for the review 🙏 I've stuck with h5 purely as it gives the ability to grab a direct link to share