feat: generate schema docs from GraphQL

[rudouglas]

1st attempt

This queries GraphQL for Endpoint information in order to be able to create Docs from them.

Currently, it looks like there's no easy way to introspectively query all associated endpoints at once. Due to the fact these endpoint names may change in the future, or new ones be introduced, it would be better to query the Base endpoint first, and then recursively query all endpoints associated with it.

The base endpoint is Nr1CatalogQuickstart. Performing an introspection query on this does not give you details on all connected endpoints. As a result we have to search through this data, which could be deeply nested, for endpoint names that start with Nr1Catalog. There are ~35 individual endpoints that we need data on, these are listed in the example-output.json file in the PR, along with examples of what the data looks like returned from GraphQL.

There doesn't seem to be any packages we can use to turn these into Markdown files, all the packages I could find only work with __schema introspection queries but, that only queries the root Query

I have figured out a single query that we can use to get all of the data we need. The initial query sends us every single queryable endpoint in New Relic GraphQl so we have to filter that down to just Nr1Catalog* endpoints. But we can now use graphql-markdown to auto-generate a Markdown doc from these results :D

[github-actions]

Thank you for your contribution, our team will be reviewing this shortly, please be available for any follow up questions or code review feedback!

[aswanson-nr]

Looks good to me! I think we may want to move to a manually defined schema doc in the future, since the nerdgraph naming conventions are a bit different than the yaml definitions. However, this totally works to replace the current auto-generated docs.
I'd just like to get @jpvajda's sign off on the generated doc before we merge

[jerelmiller]

Can we strip out internal info from the resulting markdown file?

[jerelmiller]

We may not want to expose our slack channels and field visibility publicly

[jerelmiller]

One idea to make this easy is to create a "regular" account which is non NR admin, create a key from there, and use that key to generate these docs. NerdGraph will strip this out for you in that case so that you don't need to worry about creating regexes to strip this out yourself.

[moonlight-komorebi]

quick question, do we have both sets of documentation in the repo?

should we replace the content in ./docs with the new documentation?

[jpvajda]

@nr-kkenney

should we replace the content in ./docs with the new documentation?

Maybe? I guess I'd be curious in what's the difference will be in documentation, will it be similar (better || worse) in what we currently generate in /docs with the script you created?

[moonlight-komorebi]

john and i thought this new documentation was better than the one we currently have, so we're in favor of replacing the existing docs.

did we want to delete the docs we currently have as part of this pr, as well as update any readme and other tasks, or a separate PR?

[zstix]

TODO: move into the docs/ directory.

[moonlight-komorebi]

lgtm

changes made

[nr-opensource-bot]

🎉 This PR is included in version 0.97.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀