-
Notifications
You must be signed in to change notification settings - Fork 301
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat: generate schema docs from GraphQL #765
Conversation
Thank you for your contribution, our team will be reviewing this shortly, please be available for any follow up questions or code review feedback! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can we strip out internal info from the resulting markdown file?
utils/graphql-schemas/schema-docs.md
Outdated
Information about the quickstart | ||
|
||
--- | ||
**NR Internal** | [#help-nr1-dev-experience](https://newrelic.slack.com/archives/CPE597DNY) | visibility(customer) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We may not want to expose our slack channels and field visibility publicly
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
quick question, do we have both sets of documentation in the repo? should we replace the content in ./docs with the new documentation? |
@nr-kkenney
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? |
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? |
TODO: move into the |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
lgtm
🎉 This PR is included in version 0.97.0 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
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 withNr1Catalog
. There are~35
individual endpoints that we need data on, these are listed in theexample-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 QueryI 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 usegraphql-markdown
to auto-generate a Markdown doc from these results :D